接口规范

接口规范定义资源、方法、参数、响应和错误模型，是 API 设计、文档、测试和协作的共同边界。

#tech / dev / api #type / concept #status / evergreen

接口规范

[!info] related notes

一句话定义

接口规范是调用方和实现方对资源语义、请求结构、响应格式和错误处理达成的一组共同约定。

范围

这篇笔记主要讨论 HTTP / REST 风格 API 的基础约定，不展开 GraphQL、gRPC 等其他协议体系。

边界与易混淆点

接口规范不等于某个工具

Postman 和 APIFox 是消费和组织接口资产的工具，不是接口规范本身。

接口规范也不等于 OpenAPI 工具页面

Open API Swagger 更接近“把规范写成可机读文件，并进入文档、代码生成、mock 工具链”的形式。

规范的真正价值在于成为共同边界

如果没有稳定接口规范，调试、测试、文档、mock 和版本管理都会各写各的，最后无法收敛成同一套 API 资产。

CRUD 操作接口规范

操作HTTP方法路径请求体响应体说明
增 (Create)POST/{resource}{"username":"张三","phone":"13800138000"}{ "success": true, "data": { "id": "123", ... }, "message": "创建成功" }创建新资源，请求体包含完整字段
查 (单资源)GET/{resource}/{id}-{ "success": true, "data": { "id": "123", ... } }根据ID获取单个资源
查 (多资源)GET/{resource}?page=1&size=10&gender=男-{ "success": true, "data": [{ "id": "123", ... }], "total": 100, "page": 1, "pageSize": 10 }获取资源列表，支持分页、过滤、排序参数
改 (全量更新)PUT/{resource}/{id}{"username":"张三","phone":"13900139000","gender":"男"}{ "success": true, "data": { "id": "123", ... }, "message": "更新成功" }完整更新资源，请求体包含所有字段
改 (增量更新)PATCH/{resource}/{id}{"phone":"13700137000"}{ "success": true, "data": { "id": "123", ... }, "message": "更新成功" }部分更新资源，只包含需要修改的字段
删 (单资源)DELETE/{resource}/{id}-{ "success": true, "message": "删除成功" }删除单个资源
删 (批量)POST/{resource}/batch-delete{"ids":[123,456,789]}{ "success": true, "message": "批量删除成功", "deletedCount": 3 }批量删除资源，请求体包含ID列表

说明

  • {resource}: 资源名称，如 users, posts, products 等
  • {id}: 资源唯一标识符，通常为UUID或数字ID
  • 路径参数: URL路径中的变量部分，如 /users/123 中的 123
  • 查询参数: URL中的查询字符串，如 ?page=1&size=10
  • 请求体: HTTP请求的body，通常为JSON格式
  • 响应体: HTTP响应的body，统一格式包含success、data、message字段
  • 状态码: 成功操作返回200（查询）或201（创建），失败返回4xx或5xx

错误响应格式

{
  "success": false,
  "error": "错误信息",
  "code": "ERROR_CODE",
  "details": {
    "field": "具体字段错误信息"
  }
}

常见HTTP状态码

  • 200 OK: 请求成功
  • 201 Created: 资源创建成功
  • 204 No Content: 请求成功但无返回内容
  • 400 Bad Request: 请求参数错误
  • 401 Unauthorized: 未授权
  • 403 Forbidden: 权限不足
  • 404 Not Found: 资源不存在
  • 409 Conflict: 资源冲突（如重复创建）
  • 422 Unprocessable Entity: 验证失败
  • 500 Internal Server Error: 服务器内部错误

请求类型说明

请求类型Content-Type特点适用场景示例
JSONapplication/json- 数据结构化，支持复杂嵌套
- 前后端类型安全
- 易于解析和验证
- 支持Unicode字符		- RESTful API
- 复杂数据结构
- 需要类型验证的接口		{"username":"张三","phone":"13800138000","profile":{"age":25,"city":"北京"}}
Form Datamultipart/form-data- 支持文件上传
- 支持文本和二进制数据
- 浏览器原生支持
- 边界分隔数据		- 文件上传
- 包含文件的表单
- 大数据量传输		username=张三&phone=13800138000&avatar=[文件数据]
URL Encodedapplication/x-www-form-urlencoded- 简单键值对
- URL编码特殊字符
- 数据量小
- 兼容性好		- 简单表单提交
- GET请求参数
- 传统Web表单		username=%E5%BC%A0%E4%B8%89&phone=13800138000
Texttext/plain- 纯文本数据
- 无格式要求
- 数据量大		- 日志上传
- 纯文本内容
- 特殊格式数据		这是纯文本内容，可以包含换行\n和特殊字符@#$%^&*()
XMLapplication/xml 或 text/xml- 结构化标记语言
- 企业级应用常用
- 支持复杂数据结构		- SOAP Web服务
- 企业集成
- 遗留系统		<user><username>张三</username><phone>13800138000</phone></user>

请求类型选择建议

  • 优先使用JSON: 现代Web API的首选，类型安全，易于维护
  • 文件上传用Form Data: 需要上传文件时必须使用
  • 简单表单用URL Encoded: 传统表单或简单数据
  • 特殊需求: 根据具体业务场景选择Text或XML

安全注意事项

  • JSON请求: 注意XSS攻击，服务端应验证和转义数据
  • Form Data: 文件上传需检查文件类型、大小，防止恶意文件
  • 所有请求: 实施输入验证、SQL注入防护、速率限制
创建于 2025/1/1 更新于 2026/5/27