obsidian/BACKEND/API 设计.md

---
tags: [后端, API, RESTful, 设计]
create time: 2026-04-24 18:41
---

# API 设计

## 概述

API（Application Programming Interface）是前后端协作的契约。好的 API 设计让前端开发者一看就懂、一用就会。差的 API 设计会让协作效率大幅下降。

思考题：设计一个 API 时，是应该"让所有人都符合你的设计"还是"让设计迁就所有使用场景"？这两者的边界在哪里？

## 正文

### 1. RESTful API 设计规范

**资源命名：**
- URL 用名词复数，不用动词
- 层级结构表示从属关系
- 查询参数用于筛选和排序

```
GET    /api/users              → 获取用户列表
GET    /api/users/5            → 获取用户 5 的详情
GET    /api/users/5/posts      → 获取用户 5 的所有文章
GET    /api/users?role=admin   → 筛选管理员用户
GET    /api/users?sort=-created_at  → 按创建时间倒序
GET    /api/users?page=2&limit=20  → 分页
```

### 2. 标准响应格式

```json
// 成功响应（200 OK）
{
    "code": 0,
    "message": "success",
    "data": {
        "id": 1,
        "name": "Alice",
        "email": "alice@example.com"
    }
}

// 成功响应（201 Created）
{
    "code": 0,
    "message": "created",
    "data": { "id": 5, ... }
}

// 错误响应（4xx / 5xx）
{
    "code": 1001,
    "message": "用户不存在",
    "data": null
}
```

> **提问：** 错误码设计成数字好还是字符串好？数字更紧凑但可读性差，字符串更直观但传输量大。你怎么权衡？

### 3. 常见错误码设计

| code | HTTP 状态码 | 含义 |
|------|-------------|------|
| 0 | 200 | 成功 |
| 1001 | 404 | 资源不存在 |
| 1002 | 400 | 参数校验失败 |
| 1003 | 401 | 未认证 |
| 1004 | 403 | 无权限 |
| 1005 | 429 | 请求过于频繁 |
| 2001 | 500 | 服务器内部错误 |

### 4. 分页设计

```
GET /api/users?page=1&limit=20

响应：
{
    "code": 0,
    "data": [...],           // 当前页数据
    "pagination": {
        "page": 1,
        "limit": 20,
        "total": 100,
        "total_pages": 5
    }
}
```

> **核心概念：** 客户端分页 vs 服务端分页。大数据量时必须服务端分页，否则性能灾难。

### 5. 版本控制

```
方案一：URL 路径（推荐）
/api/v1/users
/api/v2/users

方案二：请求头
Accept: application/vnd.api.v1+json
```

### 6. Go 后端 API 示例

```go
package main

import (
    "encoding/json"
    "net/http"
    "time"
)

// 统一响应结构
type APIResponse struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data"`
}

func writeJSON(w http.ResponseWriter, status int, resp APIResponse) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    json.NewEncoder(w).Encode(resp)
}

// 处理用户列表
func userListHandler(w http.ResponseWriter, r *http.Request) {
    // 1. 解析查询参数
    page, _ := strconv.Atoi(r.URL.Query().Get("page"))
    if page < 1 {
        page = 1
    }
    limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))
    if limit == 0 {
        limit = 20
    }

    // 2. 查询数据库（省略）
    users, total := getUsersFromDB(page, limit)

    // 3. 返回统一格式
    writeJSON(w, http.StatusOK, APIResponse{
        Code:    0,
        Message: "success",
        Data: map[string]interface{}{
            "users": users,
            "pagination": map[string]int{
                "page":    page,
                "limit":   limit,
                "total":   total,
                "pages":   (total + limit - 1) / limit,
            },
        },
    })
}
```

```mermaid
graph TD
    A[HTTP Request] --> B{方法检查}
    B -->|GET| C[解析查询参数]
    B -->|POST| D[解析请求体]
    C --> E[参数校验]
    D --> E
    E --> F{校验通过?}
    F -->|否| G[返回 400 + 错误信息]
    F -->|是| H[查询/操作数据库]
    H --> I{操作成功?}
    I -->|否| J[返回对应错误码]
    I -->|是| K[返回 200/201 + 数据]
```

## 关联笔记

- [[HTTP 协议]] — API 设计的基础是理解 HTTP
- [[Go 后端基础]] — Go 实现 API 的具体方法
- [[数据库基础]] — API 的数据来源
- [[30.areas/finance/Investment lessons/2024.Current trading lessons.md]]