API设计原则课件.ppt

API 设计原则 为什么设计 api · · 降低系统各部分的相互依赖 · 提高组成单元的内聚性 · 降低组成单元间的耦合程度 · 提高系统的维护性和扩展性 api 存在的形态·无处不在 · 系统 API: 依赖库， windows api ， jdk api · 应用内模块 : 同个 app 内，重用函数，类，内部库 · 应用组件进程间通信：多个 app 间 ,RPC ， socket 协议 · 公用 api ：跨服务器，对外接口， open qq ， open weixin 等 优秀 API 所具备的特征· · 简单易学：有完善的文档及提供尽可能多的示例和可 copy － paste 的 代码，像其他设计工作一样，你应该应用最小惊讶原则 易于使用：没有复杂的程序、复杂的细节，易于学习；灵活的 API 允 许按字段排序、可自定义分页、 排序和筛选等。一个完整的 API 意味 着被期望的功能都包含在内。即使没有文档； 很难误用：有详细的错误提示，有些经验的用户可以直接使用 API 而 不需要阅读文档 · · · · · 易于阅读：代码易于维护； 足够强大：可以满足需求； 易于扩展； · 适合用户 API 设计通用原则 · 1. 面向用例设计 : 面向用例的设计，收集用户建议，把自己模拟成用 户，保证 API 设计的易用和合理 · 2. 逐步改善，完全重写· -0.x 版本· 1.0 版本：第一版做尽量少的内容，由于新需求可以通 的形式完成，因此尽量少做事情是抑制 API 设计错误的一个 过扩展 有效方案 属性， - 逐步改进：保证后续的需求可以通过扩展的形式完成，加类，加 加参数，加方法，改进引入伤害最小化， - 阿米巴变形虫效应：对外描述是圆的，内部实现可以是变形的 · 3. 兼容性：向后兼容 · 4. 文档：对外提供清晰的 API 和文档规范，避免用户错误的使用 API ， 尤其是避免 API 靠后级别的 API 被用户知晓与误用； SDK ， console tools · 5. 可测试性：不依赖实现 · 6. 职责明确：一个接口实现一个业务 · 7. 高内聚低耦合：一个接口实现一个完整的业务功能，而不是多个接 口调用 · 8. 参数格式统一：不要一会儿逗号分隔，一会儿数组；日 期一会儿是 yyyyMMdd ， yyyy-MM-dd · 9. 状态和消息：告知用户成功还是失败，失败原因 · 10. 控制数据量：过多数据传输压力大，客户端反应缓慢， 是否接口划分不明· · 11. 禁止随意扩展 api 和参数：新建接口要有充分理由和考 虑，加参数必要要有意思，首先应考虑现有内部接口维护 是否能满足，不要为了方便实现加参数 HTTP API 设计原则 · 1. 使用 TLS(https) ，非 https 返回 403 · 2. 专用域名： ，简单用 /api/ · 3. 版本： /v1/ 或者加到 https head 里 accept: application/vnd.heroku+json; version=3 · 4. 路径（ Endpoint ）：名词，复数，如： /v1/zooms · 5 . 操 作 ： 动 词 ， 使 用 h t t p m e t h o d 方 法 ， get(select),post(create),put(update 完 整 ),patch(update 部 分 ),delete(delete),head( 获取元数据 ),options( 获取哪些字段可以修改 ) · 6. 过滤 (filter) ： limit,offset,page,per_page,sortby,order,animal_t ype_id · · 7. 状态码（ status code ）： 8. 错误处理 (error handling) ： { error: Invalid API key } · 9. 数据格式： json, 避免 xml · 10. 时间格式：不同时区人调用，使用 UTC 时间 · 200 OK - [GET] ：服务器成功返回用户请求的数据，该操作是幂等的 （ Idempotent ）。 · · · 201 CREATED - [POST/PUT/PATCH] ：用户新建或修改数据成功。 202 Accepted - [*] ：表示一个请求已经进入后台排队（异步任务） 204 NO CONTENT - [DELETE] ：用户删除数据成功。 · · · · · · · 400 INVALID REQUEST - [POST/PUT/PATCH] 用户发出的请求有错误 401 Unauthorized - [*] 用户没有权限（令牌、用户名、密码错误） 403 Forbidden -