API 接口格式规范

DANGER

遵循 restful 标准： restful

HTTP方法规范

• GET: 获取资源
• POST: 创建资源
• PUT: 更新资源（全量更新）
• PATCH: 更新资源（部分更新，例如状态变更、流程节点变更等）
• DELETE: 删除资源

DANGER

解释：HTTP方法表示对资源的操作类型，URL保持不变。

基础接口定义

行为	请求方式	路径	描述
新增	POST	/resource	接口一般返回新增后的记录数据（包含主键）
查分页	GET	/resource?param1=a&param2=b	返回分页数据/(小驼峰命名)
列表	GET	/resource/list	返回列表数据
查详情	GET	/resource/:id	返回详情数据
删除	DELETE	/resource/:id	接口一般返回删除状态（成功/失败）
	PUT	/resource/:id
	PATCH	/resource/:id
	PUT	/resource/:id/children/:children_id
	POST	/resource/:id/children/:children_id
	DELETE	/resource/:id/children/:children_id

自定义接口

定义	正例	反例	解释
使用名词而非动词表示资源	/api/v1/articles	/api/v1/getArticles	使用名词可以更好地表示资源，而不是操作。操作应该通过HTTP方法来表示。
使用连字符（-）来提高URL的可读性	/api/v1/blog-posts	/api/v1/blogPosts 或 /api/v1/blog_posts	连字符比下划线更容易阅读，也避免了驼峰命名可能带来的大小写敏感问题。
避免使用文件扩展名	/api/v1/users	/api/v1/users.json	使用Accept头来指定期望的响应格式，而不是在URL中指定。
使用小写字母	/api/v1/user-profiles	/api/v1/User-Profiles	统一使用小写可以避免大小写敏感带来的问题。
使用嵌套结构表示资源之间的关系	/api/v1/users/123/orders	/api/v1/users-orders/123	这种方式清晰地表示了资源之间的从属关系。

接口请求参数规范

• 接口调用者可不传递此参数，也可传递此参数名，但值为空比如有，GET 请求 /user?search=张三，其中 search 参数为可选参数，如下调用都应该视为 "未传递此参数"
  • /user
  • /user?search=

• • ****

接口响应格式

统一结构

字段	示例	说明
success	true/false	是否成功
message	错误信息
data	对象	数据

一般格式示例

{
    "success": true,
    "message": null,
    "data": [
        {
            "id": "6"
        }
    ]
}

分页格式示例

请求参数

参数	描述
page	当前页
pageSize	每页条数

响应

参数	描述
total	总数
list	分页数据列表
pageNum	当前页
pageSize	每页条数
isFirstPage	是否首页
isLastPage	是否尾页

示例：

{
      "success": true,
      "message": null,
      "data": {
        "total": 1,
        "list": [
          {
            "id": "123"
          }
        ],
        "pageNum": 1,
        "pageSize": 20,
        "isFirstPage": true,
        "isLastPage": true
      }
    }

响应状态码

成功响应

• 200 OK: 请求成功
• 201 Created: 资源创建成功
• 204 No Content: 请求成功，但无返回内容

客户端错误

• 400 Bad Request: 请求格式错误
• 401 Unauthorized: 未授权
• 403 Forbidden: 禁止访问
• 404 Not Found: 资源不存在
• 405 Method Not Allowed: 不支持的HTTP方法
• 409 Conflict: 请求冲突
• 422 Unprocessable Entity: 请求格式正确，但语义错误

服务器错误

• 500 Internal Server Error: 服务器内部错误
• 502 Bad Gateway: 网关错误
• 503 Service Unavailable: 服务不可用
• 504 Gateway Timeout: 网关超时

自定义错误(500)

在响应体message中包含详细的错误信息：

    {
        "message": "数据不存在！"
    }