Skip to main content
Version: 2.7.x

一、基本介绍​

结构化编程，简单来理解，就是通过定义结构体传递和返回参数。

我们建议在必要的场景下使用结构化定义来管理输入/输出，尤其是在 controller 和 service 两层的代码设计中。

1、 controller 非结构化痛点​

  • 难以确定接口输入/输出数据结构，大多数的场景是在代码中硬编码参数接收名称，易把名称写错造成不可预料的问题
  • 接口参数往往只定义一个 HttpRequest/HttpContext 对象指针，执行结果直接写入到对象，难以确定接口是否成功/失败
  • 参数接收、校验、转换处理工作繁琐
  • 接口文档生成以及维护极为困难

2、 service 非结构化痛点​

  • 当方法参数较多的时，定义丑陋，使用别扭
  • 当方法参数数量、类型不太确定时，任意的参数变化都是非兼容的(例如新增参数)，会引起较高的修改成本
  • 方法参数注释不简便，以至于绝大部分业务项目都不会有方法参数注释

二、结构化编程​

1、 controller 结构化改进​

结构化优点：

  • 通过结构化管理接口输入/输出参数，参数接收不再需要硬编码参数名称，降低维护成本，避免参数名称硬编码错误问题
  • 可以做到自动化的参数接收、转换、校验，提高生产力
  • 可以规范化接口编写
  • 使得接口管理能够像普通的函数管理那么方便，通过返回 error 来判断接口处理结果，并可以规范化统一错误机制
  • 使得自动化的接口文档生成变为了可能，并保障了接口结构定义和接口文档同步维护

结构化示例：

结构定义：

方法使用：

2、 service 结构化改进​

结构化优点：

  • 当方法参数较多的时，通过结构体优雅管理参数
  • 当方法参数数量、类型不太确定时，参数的增加对方法调用来说都是兼容性的
  • 对结构体属性的注释描述更加便捷，提高代码维护质量

结构化示例：

三、注意事项​

  • service 层的方法在使用结构化管理输入/输出参数时，结构体中任意参数都将会被看做非必需参数。因此需要根据业务场景合理评估可行性。