文档中心

Appearance

RESTful 接口设计规范 ​

为了确保 API 具有高一致性、可读性和易维护性，所有内部微服务与外部公开接口设计均须遵循以下标准。

1. 资源命名与路径约定 ​

API 的资源设计采用资源导向的哲学，以复数名词形式描述。

1.1 命名规范 ​

  • URL 路径: 统一使用小写字母和中划线拼接（kebab-case）。
    • 正确: /v1/device-telemetries
    • 错误: /v1/deviceTelemetries 或 /v1/device_telemetries
  • 资源名称: 使用复数名词形式，代表一个资源的集合。
    • 正确: /v1/devices, /v1/users
    • 错误: /v1/device, /v1/user
  • 子资源路由: 使用斜杠表示从属层级结构。
    • 示例: /v1/devices/{device_id}/telemetries

2. HTTP 方法映射与幂等性 ​

针对资源的操作必须使用语义准确的 HTTP 请求方法。设计必须符合以下规范：

方法语义与操作安全性幂等性常见成功响应码
GET获取单个资源详情或资源列表是是200 OK
POST在资源集合中创建新资源否否201 Created
PUT全量覆盖更新指定资源的属性否是200 OK
PATCH增量修改指定资源的部分属性否否200 OK
DELETE注销/移除某个指定的资源否是204 No Content

注：安全指不改变服务器上的资源状态；幂等指多次发起相同操作与一次操作对系统状态的影响完全等效。

3. 标准状态码对照表 ​

API 必须使用正确的 HTTP 状态码来直观传达响应的基本类型。

3.1 成功响应 (2xx) ​

  • 200 OK: 请求处理成功，数据随 Body 返回。
  • 201 Created: 新资源成功创建（如 POST 接口），响应体返回新建资源的元数据。
  • 204 No Content: 请求执行成功但响应主体无任何内容返回（通常用于 DELETE）。

3.2 客户端错误 (4xx) ​

  • 400 Bad Request: 请求格式错误、缺少必填参数或 JSON 无法解析。
  • 401 Unauthorized: 未携带凭证，或 Access Token 已过期失效。
  • 403 Forbidden: 身份校验通过，但用户不具备访问此资源的 ACL 权限。
  • 404 Not Found: 请求的 URI 路径无效，或资源物理上不存在。
  • 422 Unprocessable Entity: 请求格式正确，但业务参数检验失败（例如手机号格式不正确、字段长度超限等）。
  • 429 Too Many Requests: 请求频次超过限流窗口设定的阈值。

3.3 服务端错误 (5xx) ​

  • 500 Internal Server Error: 业务服务器发生未知内部异常或底层死锁崩溃。

4. 高级过滤与查询规范 ​

当对列表型资源（如设备列表、遥测历史）进行查询时，必须实现以下通用参数标准以实现高吞吐。

4.1 分页参数 (Pagination) ​

在大列表查询中，禁止一次性拉取所有记录，必须通过 page 和 per_page 进行控制：

  • ?page=1&per_page=15
  • 限制: per_page 最大值限定为 100，默认建议为 15。
  • 响应规范: 分页查询的 JSON 响应中必须通过包含 meta 字典来输出分页详情。

4.2 排序参数 (Sorting) ​

使用 sort 字段，多字段排序用逗号 , 分隔，降序字段前增加中划线 -：

  • 按创建时间降序: ?sort=-created_at
  • 先按状态降序、再按创建时间升序: ?sort=-status,created_at

4.3 字段过滤/投影 (Field Selection) ​

为了节省移动端带宽和降低网络载荷，客户端可通过 fields 指明只拉取哪些核心字段，多个字段使用逗号 , 分隔：

  • ?fields=id,macAddress,status
  • 服务器在收到请求后，响应体中只包含列举的这三个字段。