2022-构建 API 工程时我思考了这些点

94 阅读5分钟

本文适合准备重头开始构建一个纯的RESTful API 工程的人阅读,本文可以作为技术框架选型时的一些参考,以及确定框架后对初始化工程中需要全局统一规范处理的内容进行支持; 实际开发时不同框架不同语言会有各自的一些细小差异,故本文不具体到框架中进行描述,只在工程层面进行归纳和整理,因此本文内容不受限与语言和框架;

框架选择层面

  1. 框架社区活跃度,是否有完善的使用文档和最佳实践指南;
  2. 对性能要求较高时,需要对框架进行性能测试和评估;
  3. 明确框架的能力和边界,框架擅长的场景与当前即将构建的项目是否匹配;
  4. 框架的复杂度与团队的技术能力是否匹配,框架的优点能为团队或项目带来哪些收益?框架的缺点是否是团队和项目能承受或可控?

搭建基础项目需要考虑些什么呢?

确定工程结构

应当遵循所选择框架的最佳实践结构,再根据实际需要进行拓展,并严格执行该结构甚至是文件命名

制定开发规范和约束

  1. 文件组织结构规范(建议遵循所选框架的最佳实践,没有时可根据编程语言的规范制定);
  2. 文件命名规范,变量命名规范(建议遵循所选框架的最佳实践,没有时可根据编程语言的规范制定);
  3. 代码提交规范,可借助类似于git-commit-template 这样的工具结合githooks进行自动检测和约束

路由管理

  1. 依照框架的最佳实践进行,并默认实现一套标准的完整的CURD模板;
  2. API的鉴权验证,是借助中间件或是借助第三方服务等;
  3. 参数的校验和转换(传入参数dtoentity);
  4. 统一响应结构与http状态(成功结构体与状态,失败结构体与状态);

环境与配置管理

当有多环境的需要时,则需要考虑多环境的配置问题,是直接从环境变量中获取还是系统内多套配置,根据环境识别选用对应的配置;又或者有专门的配置中心进行管理

异常处理

  1. 除了框架提供的内置异常外我们还需要对异常进行分类并记录和上报,未捕获的全局异常,参数异常,第三方服务或中间件异常等;
  2. 搭建项目时需要对其进行先行划分并在研发过程中不断调整,并通过自定义异常的方式提供不同种类的异常给业务层使用;同时需要对这些异常进行统一的收集和上报,如果级别很高则可能还需要实时邮件或实时告警;异常发生后,需要对异常信息脱敏后以友好的方式响应给调用方;
  3. 异常日志记录时,需要同步记录触发异常的原始数据,以及触发异常源(调用堆栈)和产生错误的动作,如果有链路追踪的话就更好了,通常中小型项目是不需要的.尤其是单体独立应用,有详细的调用堆栈即可;
  4. 对于第三方服务的一些异常,如果需要则应该引入重试机制;
  5. 对于日志在不同环境的输出级别需要划分,开发和预发布环境应当越详细越好;正式环境应该提高日志级别;

第三方集成

  1. 统一第三方服务对调用方的异常响应方式(返回异常/throw异常),这会影响业务调用方的处理方式
  2. 提供统一的基础能力封装供业务层使用;
  3. 对每一个第三方提供独立的异常处理和上报机制;

运维与部署

  1. 根据框架的最佳实践进行构建和部署,进行主机部署,容器部署等;
  2. 如果有自动化测试,则还需要结合自动化进行测试
  3. 如果有CI/CD的环境则还需要编写对应的脚本以及配置

最后

  1. 选择框架时,就要尽可能依照框架的最佳实践,结合团队和项目的情况进行微调或拓展,如果你微调和拓展的内容特别多甚至出现了hack行为,那说明该框架可能并不适合当前项目或者你对该框架还不够熟悉
  2. 应该提供一定的自动化能力来解放标准化的重复性工作,文件创建,模块创建等;
  3. 如果是主要开发或负责人.则应该多研究和查阅框架文档和实践,了解框架的架构设计,并尽可能保证版本升级和更新
  4. 引入的机制或规则越多,实际开发就会越笨重,所以你应该对基础工程量体裁衣;

如果你发现文章有遗漏或其他的建议,请告诉我.

阅读原文