汇付技术丨如何设计与实现用户友好的API

在现代数字化转型中，API（Application Programming Interface应用程序编程接口）已成为技术生态的重要基石。无论是企业内部的系统集成，还是对外提供的服务能力，API用户体验直接影响企业技术价值的释放。用户友好的API不仅能够降低接入成本，还能提升开发者对平台的认可度和满意度。相信能点击进入这篇文章的读者，已经深刻认识到API在现代软件体系中的重要性。

从开发者的角度看，友好性体现在API的简洁、易理解、易用。一个用户友好的 API 应该能让开发者在最短时间内理解功能并能够顺利进行集成和调试。

与用户体验（UX）类似，开发者体验关注的是API设计和使用过程。API设计得越直观、文档越完备，开发者的工作效率就越高，出错的概率就越低。概括起来，开发者最关心的三个核心问题是：是否高效、是否安全以及是否可靠。

是否高效的问题：

1、完成API集成所需要的时间？

2、集成过程中遇见问题，API文档的探索难度大么？如果无法自己解决，开发者反馈问题后，通常需要多久才能得到响应？

3、一个问题无法在当前会话中解决，需要转化为需求。那么，从需求提出到落地的周期大约需要多长时间？

是否安全的问题：

1、认证是否有效？是否实现了细粒度的权限控制？如何防止未授权的访问？

2、如何确保传输过程中的数据不被窃取或篡改？是否采取加密存储敏感数据？能否最小化数据暴露？

是否可靠的问题：

1、在高流量或高负载下能否正常运行？API的响应时间是否符合场景需求？

2、新版本API的变更是否影响现有应用使用？

为了解决上述核心问题，我们制定了一系列API设计原则，以指导开发、测试和运维工作。

1）清晰性

命名规范

a.路径（endpoint）与参数的命名方式要简洁明了。

b.路径（endpoint）：

/{version}/{namespace}/{module}/{resource}/{action}

1.version：区分大版本（v1、v2）和小版本（2024-07-01）（1、通过语义描述版本；2、日期作为补充）

2.namespace：表示业务领域，比如trade表示交易。相关上下文的业务不应该属于不同领域

3.module：表示业务模块，如onlinepayment表示线上支付。起到归类的作用，相同应用场景具有相同的业务模块

4.resource：表示具体资源尽量通过名词表示，如quickpay表示快捷支付。应具有比较强的可读性，如果没有专门的名称，可以参考业界常用的名称

2）一致性

统一的格式和返回结构

a.使用统一的数据格式（JSON）

b.错误码与错误描述统一格式

通用的鉴权与安全策略

a.为了保证数据传输过程中的数据真实性和完整性，需要对数据进行数字签名，在接收签名数据之后进行签名校验，以验证数据报文的真实性及有效性，防止报文被恶意篡改。

b.接口调用者生成一对公私钥，私钥进行签名，公钥进行验签。

c.如果签名失败所有接口将统一返回922验签失败返回码。

3）容错性

错误处理与异常管理

a.通过建立统一的返回码库，我们可以确保所有API接口在发生错误时都能返回标准化的错误码和详细描述。

b.返回码库包括各种常见的错误类型，每种错误码都有明确的定义规则，确保不同模块间一致。并且每个返回码都配有简洁易懂的描述，帮助开发者和用户快速定位问题。

c.内部我们依赖一套完整的全链路监控系统，主要依赖于trace并辅以详细的日志，便于追踪和排查问题。

4）扩展性

API版本管理

a.对于兼容性更新，我们应遵循“向后兼容”的原则，确保新版本API在不破坏现有客户端功能的情况下，增加新特性或优化性能。而非兼容性更新则会对现有接口或功能进行较大变动，可能导致不兼容的改动，需要通过新版本发布，并对客户端进行适当的提示和引导，确保平滑迁移。

5）安全性

基础安全与传输加密

a.基础安全和传输加密是保护数据安全的关键。HTTPS协议应用到所有API通信中，确保数据在传输过程中不被窃取或篡改。

b.针对部分敏感信息如银行卡号：需要使用公钥进行加密，服务端使用私钥进行解密。应注意，部分加密工具对明文数据长度有限制。

围绕设计原则，早期斗拱沉淀了协议规范、设计原则、认证安全方式、API命名规则、数据规范、标准字段集、版本管理方法、数据模型、返回码规范、幂等校验、日志规范、文档规范等内容，但是在实际落地过程中却发现诸多难以落地、执行度不高的问题。主要集中在：

1、不同团队和开发人员未严格遵循统一的设计规范，导致API的一致性差

2、 API文档未及时更新，导致文档与实际接口实现存在偏差

3、标准字段和通用参数未被广泛应用，导致接口设计不统一

4、日志记录不规范，影响问题排查与运维

导致这些问题的关键还是大家对API的定位不一致，因此我们重新审视了API的定位。

API应该像一面旗帜，为设计与实现过程指明方向，后续的功能规划、技术选型和实现策略都会围绕这一定位而展开。

回顾原有定位，API仅是便于开发人员将服务连接在一起的小众工具。更好的定位API应该是产品。应从头开始围绕API设计所有内容，而不是构建产品然后再添加API。API不仅仅是一种技术解决方案，而是作为产品进行设计、管理和演进。以此为基础，研发模式就要从原有的Code-First转变成API-First。

1） API-First策略全景概览

· 规范层：

规范层是整个API-First策略的基础，定义了所有API的标准和规则。包括接口设计规范、数据模型规范、安全规范、命名规范等。

· 管理平台层：

管理平台层提供了API设计、开发、测试、监控和文档生成等功能的支持工具，帮助开发者和团队在规范的基础上高效协作。

· 基于API生命周期的管理层：

API生命周期管理层关注整个API从设计、开发到上线、维护的全过程，涉及API的版本控制、测试、上线发布、错误修复、监控等。

2）高效工程平台：API设计与管理的支撑体系

汇付天下秉持工程化理念，全面覆盖自动化管理研发生命周期，以满足敏捷开发和灵活适配的需求，实现高效、优质和省成本的目标，并成功构建了一套斗拱工程平台。在此基础上，进一步丰富了平台的API管理能力。

平台层是API-First策略的重要组成部分，提供了支持API全生命周期的各种工具，以便团队能够高效、准确地实施API设计、开发、测试、部署和维护。以下是平台层的一些关键工具：

· API设计工具：

通过OpenAPI定义接口的路径、请求参数、响应格式等，并提供可视化的API设计功能。

同时我们实现了一套基于SonarQube的代码门禁工具，用于自动化代码质量检查，确保API设计符合规范。检查潜在问题、代码风格一致性、安全漏洞，帮助开发团队及时发现并修复问题，有效监督规范的执行。

API文档生成工具：

所见即所得，编辑后的内容可以即时在API站点上预览，直接查看效果。
支持在线预览：单个API文档预览和整站预览，工程平台提供对外站点地址访问；
支持分享：可分享链接给其他开发者或订阅者协作与访问；
自定义主题样式：符合斗拱API站点样式，额外支持文字自定义颜色样式、超链接样式、列表样式。

API测试工具：

帮助开发人员进行手动测试、自动化测试以及集成测试，支持多种认证方式、参数化请求等。提供在线测试API的工具，直接基于OpenAPI定义进行测试。

API管理平台：

版本管理：API版本控制、版本发布与退役管理、平滑迁移、文档管理、版本隔离等功能

限流功能：结合强大的API网关能力可以实现以下限流类型：基于时间的限流、基于IP的限流、基于用户/身份的限流、动态限流、请求排队等功能。更多细节可参考文章《汇付技术丨如何建设金融级API网关》。

基于API生命周期管理

通过管理平台来实现API生命周期的全程追踪与优化，从需求评审到最终发布的每一环节都得到充分的保障。

1、需求评审阶段，平台提供需求文档管理、协作与审批功能，帮助产品经理、开发人员和业务方对API需求进行详细讨论与评审。平台帮助不同角色协作，确保需求清晰且没有歧义，并能自动生成任务列表、工作流，避免遗漏重要的API功能需求。

2、API定义阶段，为开发团队提供清晰的设计依据。API定义可以在早期阶段进行多方协作，自动化生成接口文档，并进行版本控制。

3、设计评审阶段确保API的设计符合规范，兼容性以及易于扩展。平台提供设计评审流程的自动化，记录每个设计阶段的意见和决策，并允许团队成员快速反馈问题，优化API设计。

4、程序实现阶段根据API定义，完成API的编码和实现。开发阶段可以使用OpenAPI Generator等工具自动生成代码框架，通过自动化减少人为错误，提升代码的质量和开发速度。

5、测试阶段帮助团队快速定位问题并修复。通过与CI/CD工具集成，API自动化测试可以在每次代码提交后自动触发，提高效率。

6、验收发布阶段平台提供自动化部署和回滚功能，确保API版本的管理清晰，减少人为错误，同时能够快速响应生产环境中的问题。