📚 课程目录第3章接口设计原则

接口设计原则：RESTful风格、参数规范、返回格式

接口设计这件事，我觉得它跟写代码一样——干净、可预测、好维护。做了这么多年SDK，我亲眼见过因为接口风格混乱，导致客户端和服务器来回扯皮的场景。说白了，接口就是服务跟调用者之间的契约。契约写得模糊，早晚要吵架。

这一章，我带你过三个核心支柱：RESTful风格、参数规范、返回格式。它们合在一起，就是你设计KMS SDK接口时最需要盯住的骨架。

RESTful风格——以资源为中心

我个人对RESTful的理解很简单：你的URL应该对应“资源”，而不是“动作”。说白了，你是在跟一堆实体打交道（比如密钥、凭证、策略），而不是在调用一堆函数。

资源路径命名：用名词复数，比如 /v1/keys、/v1/secrets。别搞出 /getKey、/deleteSecret 这种像RPC一样的路径。
HTTP方法映射：GET是查询，POST是创建，PUT是全覆盖更新，PATCH是局部更新，DELETE是删除。这个映射表，我建议团队所有人都贴在墙上。
子资源关联：比如 /v1/keys/{keyId}/versions，表示某密钥下的所有版本。这样设计，URL本身就是一份文档。

我的经验：曾经有一个项目，老接口用 /api?action=getKey&id=123 来查密钥。后来做SDK时，我们要为每个action写一个封装方法，参数还得手动拼。那感觉，就像是接口在反向“调戏”你。后来重构成 RESTful，所有客户端生成代码几乎零配置——路径即API，舒服。

避坑指南：HTTP状态码别乱用。200永远是成功，4xx是调用方问题，5xx是服务端问题。我见过有人为了省事，所有响应都返回200然后在Body里报错。结果客户端日志里全绿的200，监控系统一片祥和，实际上业务全崩了。你想想看，那画面多恐怖。

参数规范——请对你的调用者好一点

参数设计得好，调用者几乎不需要看文档；设计得差，文档翻烂了还会传错。我个人习惯用这几条铁律：

规范维度	推荐做法	反面案例
参数命名	统一小驼峰：`keyId`、`pageSize`	混用下划线：`key_id`、`page_size`
参数类型	显式声明，比如 `int64`、`string`、`datetime`	弱类型，比如所有参数都用 `string`
必选与非必选	必选参数放路径里，非必选放查询或Body	全部放Body，连资源ID都不例外
默认值	非必选参数提供合理默认值	非必选不设默认，调用者必须传
公共参数	放到HTTP HEADER里：`X-Request-Id`、`Authorization`	放到Body里，每层透传

// 推荐示例：创建密钥接口
// POST /v1/keys
// Header: Authorization, X-Request-Id
// Body:
{
  "name": "my-key",
  "keyType": "AES_256",
  "expireAt": "2026-12-31T23:59:59Z",  // 非必选，默认永不过期
  "tags": { "env": "production" }      // 非必选，默认空
}

我踩过的坑：参数类型混用。曾经有个接口，pageSize 在文档里写的是 string，但实际服务端解析却是 integer。客户端传了个 "10"，有的版本能用，有的版本报 400。后来我强制所有 SDK 在做参数校验时，用显式类型转换 + 报错提示。嗯，这种低级错误最折腾人。

返回格式——最后1公里的体感

接口返回的数据格式，是调用者最直接的体感。我觉得，返回格式设计得好，调用者能闭着眼睛写异常处理；设计得差，他们得每调一个接口，就开一次调试器。

统一响应结构：所有接口（不管成功还是失败）返回同一种JSON壳。我推荐这样：

// 成功示例
{
  "code": 0,
  "message": "Success",
  "data": {
    "keyId": "key-abc123",
    "name": "my-key"
  }
}

// 失败示例
{
  "code": 40001,
  "message": "密钥名称不能为空",
  "data": null
}

记住：HTTP状态码只解决传输层面的问题（比如401未授权、404路径不存在）。业务层面的错误，一定要靠响应体里的 code 字段来区分。

code：整型，0表示成功，非0表示某类错误。我建议内部维护一个错误码表，按模块分区间（比如 40000~49999 是客户端错误，50000~59999 是服务端错误）。
message：人类可读的错误信息。多语言场景下可以加 message_i18n。
data：实际业务数据。失败时为 null 或空对象。

小技巧：对于列表接口，额外返回 totalCount、pageNumber、pageSize 这些元数据，放到 data 外层，还是 data 内部？我习惯放在 data 字段的同级，加一个 pagination 对象，这样分页信息不与列表数据混在一起，调用者解析起来更清晰。

核心观点：返回格式的可预测性，决定了SDK客户端能否做统一的错误处理和重试逻辑。如果每个接口返回结构都不一样，你的SDK代码里就全是 if-else 和 try-catch，维护成本直线上升。我记得有一次，因为对方接口返回格式混乱，我不得不在SDK里写了一个兼容层，针对40+个接口做特殊解析——那感觉，就像在跟屎山搏斗。

总结一句话

接口设计原则，本质上就是降低调用者的心智负担。RESTful让路径可读，参数规范让调用可猜，返回格式让错误可处理。这三样做到了，你的KMS SDK接口就赢了一大半。