核心要点
一致与清晰：命名规范统一，资源/动词语义明确（RESTful 用资源建模，RPC 用动作建模，按场景选）
健壮契约：合理使用 HTTP 状态码、统一的错误结构（错误码+可读信息）、写操作尽量幂等
可演进：从一开始就版本化、坚持向后兼容，新增字段不破坏老客户端，弃用要有过渡期
可用性与防护：提供分页、过滤、限流与鉴权，并配齐文档和可运行示例
标准回答
一致性与清晰的资源模型
好 API 首先要可预测：命名、复数/单数、时间格式、分页参数全局统一，让人猜得到下一个接口长什么样。RESTful 风格以资源建模、用 HTTP 动词表达操作；强动作或复杂调用场景下 RPC/GraphQL 更合适——按场景选，别教条。
健壮的契约：状态码、错误与幂等
正确使用状态码（2xx 成功、4xx 客户端错、5xx 服务端错），返回统一的错误结构（稳定的错误码 + 可读 message + 必要的细节）。写操作尽量设计成幂等（如用幂等键），让客户端可安全重试，避免重复扣款这类问题。
可演进与可用性
从第一版就引入版本化并坚持向后兼容：只增不改、字段弃用走通知与过渡期，不在小版本里做破坏性变更。再加上分页/过滤、限流、鉴权与清晰的认证模型保障可用性与安全。最后用准确的文档和可运行示例降低接入成本——文档质量本身就是 API 质量的一部分。
常见误区
⚠️ 常见踩坑
在已发布接口上随意改字段/语义破坏向后兼容；用 200 包裹所有错误、错误信息不可机读；漏掉分页与限流导致大查询拖垮服务。好 API 要稳定契约、合理状态码、可演进且自带文档。
追问
追问 1：API 版本化有哪些做法，如何保证向后兼容？
常见做法：URL 路径版本（/v1/）、请求头版本、或参数版本，路径版本最直观常用。向后兼容的关键是"只增不改"：新增可选字段和接口、不删除或改变已有字段语义、不收紧已有校验；确需破坏性变更时升大版本并保留旧版本一段时间，配合弃用通知和迁移文档让调用方平滑过渡。
追问 2：为什么写接口要追求幂等？怎么实现？
网络会超时重试，幂等保证同一请求重复执行结果不变，避免重复创建或重复扣款。GET/PUT/DELETE 天然幂等，POST 需额外设计：常见做法是客户端带一个幂等键（Idempotency-Key），服务端首次处理后缓存结果，重复同键请求直接返回首次结果而不再执行副作用。
延伸学习
与本题相关的知识库文章、术语、工具与行业资讯。