[代码规范]接口设计规范
一个优雅的接口要如何设计？有哪些设计规范可以遵循？
下面抛砖引玉，分享一些规范。
目录
1、RESTful API 设计最佳实践
2、Shneiderman 的 8 条黄金法则
3、Nielsen 的 10 条启发式规则
1、RESTful API 设计最佳实践
一共18条，参考了网上流传的18条规范并加以整理，基于 RESTful 规范源自微服务经验和企业实践。
包括了安全性、稳定性、可靠性、可拓展性、一致性、可维护型、高性能设计等方面。
适用于日常API开发，但要值得注意的是，通常接口开发的“快且正确的完成业务”优先级最高。
一个小的设计哲学口号：快速、可靠、优质
- 签名
- 指通过签名（如 HMAC-SHA256）验证请求的完整性和来源，常见于安全设计。
- 来源：API 安全最佳实践。
- 加密
- 数据传输使用 HTTPS，或对敏感字段加密（如 AES）。
- 来源：网络安全规范。
- IP 白名单
- 限制接口访问仅允许特定 IP，提升安全性。
- 来源：服务端安全策略。
- 限流
- 通过令牌桶或漏桶算法限制请求频率，防止接口被滥用。
- 来源：系统稳定性设计（如 Rate Limiting）。
- 参数校验
- 对输入参数进行验证（如非空、格式），避免非法请求。
- 来源：《阿里巴巴 Java 开发手册》或其他开发规范。
- 统一返回值
- 返回格式一致（如 JSON，含 code、message、data），便于调用方解析。
- 来源：RESTful API 设计准则。
- 统一封装异常
- 通过全局异常处理器返回标准错误响应。
- 来源：Java 开发最佳实践。
- 请求日志
- 记录请求信息（如时间、参数、IP），便于追踪和调试。
- 来源：运维和日志管理规范。
- 幂等设计
- 确保重复请求不产生副作用（如使用唯一标识）。
- 来源：RESTful API 设计原则。
- 限制记录条数
- 分页接口限制返回条数（如默认 20 条），避免性能问题。
- 来源：数据库查询优化。
- 压测
- 接口上线前进行压力测试，确保性能和稳定性。
- 来源：软件测试规范。
- 异步处理
- 耗时操作使用异步（如消息队列），提升响应速度。
- 来源：高并发系统设计。
- 数据脱敏
- 对敏感数据（如手机号）脱敏显示，保护隐私。
- 来源：数据安全和合规性要求（如 GDPR）。
- 完整的接口文档
- 提供详细的 API 文档（如 Swagger），包括参数、示例等。
- 来源：API 开发规范。
- 请求方式
- 使用合适的 HTTP 方法（如 GET、POST、PUT、DELETE）。
- 来源：RESTful API 规范。
- 请求头
- 定义标准请求头（如 Content-Type、Authorization）。
- 来源：HTTP 协议和 API 设计。
- 批量操作
- 支持批量请求，减少网络开销。
- 来源：性能优化实践。
- 职责单一
- 接口功能单一，避免“大杂烩”设计。
- 来源：SOLID 原则（单一职责原则）。
2、Shneiderman 的 8 条黄金法则
源自《Designing the User Interface》，这些法则最初针对图形用户界面（GUI）设计，但也广泛适用于 API 接口、Web 页面、移动应用等。
- 保持一致性（Strive for Consistency）
- 界面风格、术语、布局、操作应在整个系统中保持一致。例如，按钮样式、颜色、命名等应统一，避免用户混淆。
- 示例：所有“保存”按钮都使用绿色，且位于右下角。
- 支持快捷操作（Enable Frequent Users to Use Shortcuts）
- 为熟练用户提供快捷方式（如键盘快捷键、命令行），提高效率。
- 示例：Ctrl+S 保存，Ctrl+C 复制。
- 提供信息反馈（Offer Informative Feedback）
- 对用户的每个操作提供及时、清晰的反馈，告知结果或状态。
- 示例：点击“提交”后显示“提交成功”或“正在处理”提示。
- 设计对话框以体现完成感（Design Dialogs to Yield Closure）
- 操作流程应有明确的开始、中间和结束，让用户感到任务已完成。
- 示例：表单提交后显示“感谢您的提交”并关闭窗口。
- 预防和处理错误（Offer Error Prevention and Simple Error Handling）
- 设计时尽量避免用户犯错；发生错误时，提供简单易懂的解决方法。
- 示例：输入框限制只能输入数字，或错误时提示“请输入有效邮箱”。
- 支持撤销和重做（Permit Easy Reversal of Actions）
- 用户应能轻松撤销误操作，降低操作压力。
- 示例：删除文件后提供“撤销”选项。
- 增强用户控制感（Support Internal Locus of Control）
- 让用户感觉自己在掌控系统，而不是被系统牵制。
- 示例：允许用户随时取消长时间运行的任务。
- 减少短期记忆负担（Reduce Short-Term Memory Load）
- 界面设计应避免用户记住过多信息，提供提示或默认值。
- 示例：表单自动填充常用选项，而不是让用户每次手动输入。
3、Nielsen 的 10 条启发式规则
源自 Nielsen Norman Group官网，这些规则广泛应用于 UI/UX 设计，包括网站、移动应用、软件界面等。虽然主要针对用户界面，但部分原则（如一致性、错误处理）也可启发 API 设计。
- 系统状态可见性（Visibility of System Status）
- 用户应随时知道系统当前状态，提供及时反馈。
- 示例：上传文件时显示进度条。
- 系统与现实匹配（Match Between System and the Real World）
- 使用用户熟悉的语言和概念，避免技术术语。
- 示例：购物车图标表示“添加购物车”。
- 用户控制与自由（User Control and Freedom）
- 提供撤销和重做功能，让用户能纠正错误。
- 示例：浏览器中的“后退”按钮。
- 一致性与标准（Consistency and Standards）
- 界面元素、术语和行为应保持一致，遵循行业标准。
- 示例：所有页面顶部都有导航栏。
- 错误预防（Error Prevention）
- 设计时避免用户犯错，提供约束或确认机制。
- 示例：提交表单前要求确认。
- 识别优于回忆（Recognition Rather than Recall）
- 减少用户记忆负担，提供可见的选项或提示。
- 示例：下拉菜单代替手动输入日期。
- 灵活性与效率（Flexibility and Efficiency of Use）
- 满足新手和专家需求，支持快捷方式。
- 示例：支持鼠标点击和键盘快捷键。
- 简洁美观的设计（Aesthetic and Minimalist Design）
- 只显示相关信息，避免无关内容干扰。
- 示例：登录页面只包含用户名和密码字段。
- 帮助用户识别、诊断和恢复错误（Help Users Recognize, Diagnose, and Recover from Errors）
- 错误信息应清晰易懂，并提供解决方案。
- 示例：“密码错误，请重试或点击‘忘记密码’”。
- 帮助与文档（Help and Documentation）
- 提供易于搜索和理解的帮助文档。