接口设计原则

好的接口像一份稳定合同：语义清楚、变更可控、错误可预期。

1. 面向资源，而不是面向页面

尽量用资源名表达能力，例如 /api/hitokoto 比 /api/getText1 更清晰。 动作可通过 HTTP 方法或明确动词路径表达。

2. 返回结构保持稳定

统一 code / msg / data，避免有的接口直接返回数组、有的返回对象、有的只返回字符串。 结构稳定后，客户端拦截器、日志和监控都更好做。

3. 参数要可发现

• 必填参数越少越好，给合理默认值
• 枚举值写进文档，并在服务端严格校验
• 范围类参数（长度、页码、size）设置上下限

4. 版本策略提前想

不兼容变更时使用路径版本（如 /api/v2/...）或请求头版本， 并给出迁移窗口，而不是悄悄改字段含义。

5. 幂等与重试

写操作要考虑重复提交；读操作天然更适合重试。 对可能超时的接口，文档中写明是否允许重试。