后端 API 设计实践：从"能用"到"好用"

前言

很多团队的 API 是"长出来"的：接口越加越多、命名越来越乱、版本没人敢动。好的 API 设计不是炫技，而是让调用方少猜、维护方少改。本文总结一套经过实战验证的设计准则。

一、资源优先的 URL 设计

REST 的核心是把一切看作资源，URL 表示资源本身，HTTP 方法表示操作：

GET    /api/v1/articles          列表（支持分页、筛选）
POST   /api/v1/articles          创建
GET    /api/v1/articles/42       详情
PATCH  /api/v1/articles/42       部分更新
DELETE /api/v1/articles/42       删除

几条容易踩坑的规则：

• 用名词复数，不用动词：POST /articles 而不是 POST /createArticle。
• 层级不超过两层：/users/1/orders 可以，/users/1/orders/2/items/3/photos 就该拆了。
• 动作类接口用子资源表达：取消订单 → POST /orders/42/cancellation，比 POST /cancelOrder 更一致。
• 筛选、分页放 Query 参数：GET /articles?page=2&size=20&status=published&sort=-created_at。

二、统一响应结构

给所有接口定一个统一的响应外壳，调用方只需写一次解析逻辑：

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [{ "id": 42, "title": "..." }],
    "pagination": { "page": 1, "size": 20, "total": 133 }
  }
}

要点：

• 列表接口必须带分页元信息，否则前端无法做"加载更多"。
• 错误时 data 置空，code 使用业务错误码，HTTP 状态码表达传输层语义（401 未认证、403 无权限、404 不存在、422 参数错误、500 服务端异常）。
• 不要"所有请求都返回 200 + code 区分"——网关、监控、重试中间件都依赖真实状态码。

三、参数校验：在边界处拦截

校验逻辑应该集中在接口入口（Controller / DTO 层），而不是散落在 Service 各处。以 NestJS + class-validator 为例：

export class CreateArticleDto {
  @IsString()
  @Length(1, 100)
  title!: string;

  @IsOptional()
  @IsIn(['draft', 'published'])
  status?: 'draft' | 'published';
}

原则：非法请求在边界就返回 422 并附上字段级错误说明，绝不让脏数据进入业务层。

四、幂等与并发

• 创建类接口支持幂等键：客户端生成 Idempotency-Key 头，服务端按 key 去重，避免网络重试导致重复下单。
• 更新类接口带乐观锁：数据带 version 字段，PATCH 时携带，不匹配返回 409。
• 删除尽量软删除：deleted_at 标记，保留恢复和审计能力。

五、版本化与演进

• 路径版本最直观：/api/v1/...。破坏性变更（删字段、改语义）才升版本。
• 只加不改是延长 API 生命周期的关键：新增可选字段不算破坏性变更；必须变更时，旧字段先标记 deprecated，观察调用方迁移后再下线。
• 给每个接口写文档（OpenAPI / Swagger），并让文档从代码生成，而不是手写后忘了更新。

六、安全底线清单

• [ ] 认证：JWT / Session 过期时间合理，Refresh Token 可吊销
• [ ] 授权：每个接口校验资源归属（防止水平越权，IDOR 是最常见漏洞）
• [ ] 限流：登录、注册、发送验证码等接口按 IP + 账号双维度限流
• [ ] 输入：所有查询参数白名单化，防止批量赋值漏洞（Mass Assignment）
• [ ] 日志：不打印密码、Token、身份证等敏感字段

总结

好的 API 设计可以浓缩为四个词：一致、可预测、有边界、可演进。先定规范再写代码，后期会省下大量"改接口联调"的成本。如果你的团队还没有成文的 API 规范，不妨把本文作为起点，按自己的技术栈补充细节。