[代码规范]接口设计规范

一个优雅的接口要如何设计？有哪些设计规范可以遵循？

下面抛砖引玉，分享一些规范。

目录

1、RESTful API 设计最佳实践

2、Shneiderman 的 8 条黄金法则

3、Nielsen 的 10 条启发式规则

1、RESTful API 设计最佳实践

一共18条，参考了网上流传的18条规范并加以整理，基于 RESTful 规范源自微服务经验和企业实践。

包括了安全性、稳定性、可靠性、可拓展性、一致性、可维护型、高性能设计等方面。

适用于日常API开发，但要值得注意的是，通常接口开发的“快且正确的完成业务”优先级最高。

一个小的设计哲学口号：快速、可靠、优质

1. 签名
   • 指通过签名（如 HMAC-SHA256）验证请求的完整性和来源，常见于安全设计。
   • 来源：API 安全最佳实践。
2. 加密
   • 数据传输使用 HTTPS，或对敏感字段加密（如 AES）。
   • 来源：网络安全规范。
3. IP 白名单
   • 限制接口访问仅允许特定 IP，提升安全性。
   • 来源：服务端安全策略。
4. 限流
   • 通过令牌桶或漏桶算法限制请求频率，防止接口被滥用。
   • 来源：系统稳定性设计（如 Rate Limiting）。
5. 参数校验
   • 对输入参数进行验证（如非空、格式），避免非法请求。
   • 来源：《阿里巴巴 Java 开发手册》或其他开发规范。
6. 统一返回值
   • 返回格式一致（如 JSON，含 code、message、data），便于调用方解析。
   • 来源：RESTful API 设计准则。
7. 统一封装异常
   • 通过全局异常处理器返回标准错误响应。
   • 来源：Java 开发最佳实践。
8. 请求日志
   • 记录请求信息（如时间、参数、IP），便于追踪和调试。
   • 来源：运维和日志管理规范。
9. 幂等设计
   • 确保重复请求不产生副作用（如使用唯一标识）。
   • 来源：RESTful API 设计原则。
10. 限制记录条数
    • 分页接口限制返回条数（如默认 20 条），避免性能问题。
    • 来源：数据库查询优化。
11. 压测
    • 接口上线前进行压力测试，确保性能和稳定性。
    • 来源：软件测试规范。
12. 异步处理
    • 耗时操作使用异步（如消息队列），提升响应速度。
    • 来源：高并发系统设计。
13. 数据脱敏
    • 对敏感数据（如手机号）脱敏显示，保护隐私。
    • 来源：数据安全和合规性要求（如 GDPR）。
14. 完整的接口文档
    • 提供详细的 API 文档（如 Swagger），包括参数、示例等。
    • 来源：API 开发规范。
15. 请求方式
    • 使用合适的 HTTP 方法（如 GET、POST、PUT、DELETE）。
    • 来源：RESTful API 规范。
16. 请求头
    • 定义标准请求头（如 Content-Type、Authorization）。
    • 来源：HTTP 协议和 API 设计。
17. 批量操作
    • 支持批量请求，减少网络开销。
    • 来源：性能优化实践。
18. 职责单一
    • 接口功能单一，避免“大杂烩”设计。
    • 来源：SOLID 原则（单一职责原则）。

2、Shneiderman 的 8 条黄金法则

源自《Designing the User Interface》，这些法则最初针对图形用户界面（GUI）设计，但也广泛适用于 API 接口、Web 页面、移动应用等。

1. 保持一致性（Strive for Consistency）
   • 界面风格、术语、布局、操作应在整个系统中保持一致。例如，按钮样式、颜色、命名等应统一，避免用户混淆。
   • 示例：所有“保存”按钮都使用绿色，且位于右下角。
2. 支持快捷操作（Enable Frequent Users to Use Shortcuts）
   • 为熟练用户提供快捷方式（如键盘快捷键、命令行），提高效率。
   • 示例：Ctrl+S 保存，Ctrl+C 复制。
3. 提供信息反馈（Offer Informative Feedback）
   • 对用户的每个操作提供及时、清晰的反馈，告知结果或状态。
   • 示例：点击“提交”后显示“提交成功”或“正在处理”提示。
4. 设计对话框以体现完成感（Design Dialogs to Yield Closure）
   • 操作流程应有明确的开始、中间和结束，让用户感到任务已完成。
   • 示例：表单提交后显示“感谢您的提交”并关闭窗口。
5. 预防和处理错误（Offer Error Prevention and Simple Error Handling）
   • 设计时尽量避免用户犯错；发生错误时，提供简单易懂的解决方法。
   • 示例：输入框限制只能输入数字，或错误时提示“请输入有效邮箱”。
6. 支持撤销和重做（Permit Easy Reversal of Actions）
   • 用户应能轻松撤销误操作，降低操作压力。
   • 示例：删除文件后提供“撤销”选项。
7. 增强用户控制感（Support Internal Locus of Control）
   • 让用户感觉自己在掌控系统，而不是被系统牵制。
   • 示例：允许用户随时取消长时间运行的任务。
8. 减少短期记忆负担（Reduce Short-Term Memory Load）
   • 界面设计应避免用户记住过多信息，提供提示或默认值。
   • 示例：表单自动填充常用选项，而不是让用户每次手动输入。

3、Nielsen 的 10 条启发式规则

源自 Nielsen Norman Group官网，这些规则广泛应用于 UI/UX 设计，包括网站、移动应用、软件界面等。虽然主要针对用户界面，但部分原则（如一致性、错误处理）也可启发 API 设计。

1. 系统状态可见性（Visibility of System Status）
   • 用户应随时知道系统当前状态，提供及时反馈。
   • 示例：上传文件时显示进度条。
2. 系统与现实匹配（Match Between System and the Real World）
   • 使用用户熟悉的语言和概念，避免技术术语。
   • 示例：购物车图标表示“添加购物车”。
3. 用户控制与自由（User Control and Freedom）
   • 提供撤销和重做功能，让用户能纠正错误。
   • 示例：浏览器中的“后退”按钮。
4. 一致性与标准（Consistency and Standards）
   • 界面元素、术语和行为应保持一致，遵循行业标准。
   • 示例：所有页面顶部都有导航栏。
5. 错误预防（Error Prevention）
   • 设计时避免用户犯错，提供约束或确认机制。
   • 示例：提交表单前要求确认。
6. 识别优于回忆（Recognition Rather than Recall）
   • 减少用户记忆负担，提供可见的选项或提示。
   • 示例：下拉菜单代替手动输入日期。
7. 灵活性与效率（Flexibility and Efficiency of Use）
   • 满足新手和专家需求，支持快捷方式。
   • 示例：支持鼠标点击和键盘快捷键。
8. 简洁美观的设计（Aesthetic and Minimalist Design）
   • 只显示相关信息，避免无关内容干扰。
   • 示例：登录页面只包含用户名和密码字段。
9. 帮助用户识别、诊断和恢复错误（Help Users Recognize, Diagnose, and Recover from Errors）
   • 错误信息应清晰易懂，并提供解决方案。
   • 示例：“密码错误，请重试或点击‘忘记密码’”。
10. 帮助与文档（Help and Documentation）
    • 提供易于搜索和理解的帮助文档。