API 设计指南

良好的 API 设计提升开发效率，降低维护成本。本文介绍 IMS 系统的 API 设计规范，包括 RESTful 风格、版本管理、文档生成等。

一、RESTful 设计原则

• 资源导向：用名词表示资源，如 /users、/orders
• HTTP 动词：GET 查询、POST 创建、PUT 更新、DELETE 删除
• 语义明确：URL 只表示资源，动作由 HTTP 方法决定

/* 用户管理 API 示例 */
GET    /api/users              /* 获取用户列表 */
GET    /api/users/{id}         /* 获取单个用户 */
POST   /api/users              /* 创建用户 */
PUT    /api/users/{id}         /* 更新用户 */
DELETE /api/users/{id}         /* 删除用户 */

/* 订单相关操作 */
GET    /api/orders             /* 订单列表 */
GET    /api/orders/{id}        /* 订单详情 */
POST   /api/orders             /* 创建订单 */
POST   /api/orders/{id}/pay    /* 支付订单（动作用 POST） */
POST   /api/orders/{id}/cancel /* 取消订单 */

二、请求响应规范

统一响应格式

/* 成功响应 */
{
  "code": 0,
  "message": "success",
  "data": { ... }
}

/* 分页响应 */
{
  "code": 0,
  "data": {
    "list": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

/* 错误响应 */
{
  "code": 1001,
  "message": "参数错误",
  "data": null
}

分页参数

/* 分页请求 */
GET /api/users?page=1&pageSize=20&sort=createdAt,desc

三、版本管理

在 URL 或 Header 中体现版本：

/* URL 版本（推荐） */
GET /api/v1/users
GET /api/v2/users

/* Header 版本 */
Accept: application/vnd.ims.v1+json

四、错误码设计

• 0：成功
• 1000-1999：鉴权相关（1001 用户不存在，1002 密码错误，1003 token 过期）
• 2000-2999：业务相关（2001 库存不足，2002 订单不存在）
• 5000-5999：系统相关（5001 服务异常，5002 数据库错误）

五、API 文档生成

/* Spring Boot + SpringDoc OpenAPI */
/* pom.xml 添加依赖 */

    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.0.0

/* Swagger 访问地址 */
https://api.ims.js.cn/swagger-ui.html
https://api.ims.js.cn/v3/api-docs

六、总结

• RESTful 风格：资源 + HTTP 动词
• 统一响应格式：code + message + data
• URL 版本管理，兼容性好
• 用 Swagger/OpenAPI 自动生成文档