接口文档

API设计规范

- 所有API都应遵循RESTful架构风格。
- API路径应使用名词复数形式，如`/api/v1/users`。
- API方法应使用HTTP动词，如`GET`、`POST`、`PUT`、`DELETE`等。
- API响应应使用JSON格式，包含状态码、消息描述和数据。
- API文档应使用Swagger/OpenAPI规范，提供详细的接口说明和示例。
- 接口文档地址：http://192.168.31.10:48080/doc.html

RESTful API规范

 # ✅ RESTful API示例
   GET    /api/v1/users           # 获取用户列表
   GET    /api/v1/users/{id}      # 获取用户详情
   POST   /api/v1/users           # 创建用户
   PUT    /api/v1/users/{id}      # 更新用户
   DELETE /api/v1/users/{id}      # 删除用户
   PATCH  /api/v1/users/{id}      # 部分更新用户

请求/响应规范

// ✅ 请求参数规范
interface UserListRequest {
  page?: number;        // 页码，默认1
  size?: number;        // 每页数量，默认20，最大100
  keyword?: string;     // 搜索关键词
  status?: UserStatus;  // 状态筛选
  sortBy?: string;      // 排序字段
  sortOrder?: 'asc' | 'desc';  // 排序方向
}

// ✅ 响应格式规范
interface ApiResponse<T> {
  code: number;         // 状态码：200成功，其他失败
  message: string;      // 消息描述
  data: T;             // 响应数据
  timestamp: number;    // 时间戳
  requestId: string;    // 请求ID，用于追踪
}

interface PageResponse<T> {
  items: T[];          // 数据列表
  total: number;       // 总记录数
  page: number;        // 当前页码
  size: number;        // 每页大小
  pages: number;       // 总页数
}

状态码规范

状态码	含义	使用场景
200	OK	请求成功
201	Created	创建成功
400	Bad Request	参数错误
401	Unauthorized	未认证
403	Forbidden	无权限
404	Not Found	资源不存在
409	Conflict	资源冲突
422	Unprocessable Entity	验证失败
429	Too Many Requests	请求过多
500	Internal Server Error	服务器错误
502	Bad Gateway	网关错误
503	Service Unavailable	服务不可用
504	Gateway Timeout	网关超时