5.6.1 程序如何互相调用——接口设计

一句话破题

接口设计就是定义前后端如何对话：谁发起、说什么、怎么回应。

RESTful API 基础

REST 是一种设计风格，核心思想是把一切当作资源：

HTTP 方法	含义	示例
GET	获取资源	GET /posts - 获取文章列表
POST	创建资源	POST /posts - 创建文章
PUT	更新资源（全量）	PUT /posts/1 - 更新文章
PATCH	更新资源（部分）	PATCH /posts/1 - 部分更新
DELETE	删除资源	DELETE /posts/1 - 删除文章

接口设计模板

## POST /api/posts

### 功能描述
创建新文章

### 请求参数
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | 是 | 文章标题，1-100 字符 |
| content | string | 是 | 文章内容，Markdown 格式 |
| categoryId | string | 是 | 分类 ID |
| tags | string[] | 否 | 标签数组，最多 5 个 |

### 请求示例
```json
{
  "title": "我的第一篇文章",
  "content": "# Hello\n这是内容",
  "categoryId": "cat_123",
  "tags": ["技术", "教程"]
}

响应示例

{
  "id": "post_456",
  "title": "我的第一篇文章",
  "slug": "my-first-post",
  "createdAt": "2024-01-15T10:00:00Z"
}

错误响应

状态码	错误码	说明
400	MISSING_TITLE	标题不能为空
400	TITLE_TOO_LONG	标题超过 100 字符
401	UNAUTHORIZED	未登录

### URL 设计规范

✅ 好的设计 GET /api/posts # 获取文章列表 GET /api/posts/:id # 获取单篇文章 POST /api/posts # 创建文章 PUT /api/posts/:id # 更新文章 DELETE /api/posts/:id # 删除文章 GET /api/posts/:id/comments # 获取文章的评论

❌ 不好的设计 GET /api/getPostList # 动词不该出现在 URL POST /api/createPost # 动词重复 GET /api/post/1/comment # 单复数不一致

### 分页与过滤

```markdown
## 列表接口通用参数

### 分页
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| page | number | 1 | 页码 |
| pageSize | number | 10 | 每页数量 |

### 排序
| 参数 | 类型 | 说明 |
|------|------|------|
| sortBy | string | 排序字段 |
| order | "asc" \| "desc" | 排序方向 |

### 过滤
| 参数 | 类型 | 说明 |
|------|------|------|
| categoryId | string | 按分类筛选 |
| keyword | string | 关键词搜索 |

### 响应格式
```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 100,
    "totalPages": 10
  }
}

### 让 AI 帮你设计接口

你：帮我设计博客系统的 API 接口

AI：## 博客系统 API 设计

文章模块

方法	路径	说明
GET	/api/posts	获取文章列表
GET	/api/posts/:slug	获取文章详情
POST	/api/posts	创建文章
PUT	/api/posts/:id	更新文章
DELETE	/api/posts/:id	删除文章

分类模块

方法	路径	说明
GET	/api/categories	获取分类列表
POST	/api/categories	创建分类

认证模块

方法	路径	说明
POST	/api/auth/login	登录
POST	/api/auth/logout	登出
GET	/api/auth/me	获取当前用户

### 接口版本管理

当接口需要破坏性变更时：

方案一：URL 路径版本 /api/v1/posts /api/v2/posts

方案二：Header 版本 Accept: application/vnd.blog.v1+json

对于个人项目，建议使用 URL 路径版本，更直观。

### 实用建议

1. **保持一致性**：所有接口风格统一
2. **先设计后实现**：写代码前先把接口定义好
3. **用 AI 检查**：让 AI 帮你发现设计问题
4. **文档即代码**：用 TypeScript 类型定义接口