Midway 后端代码的设计建议

Midway 是阿里巴巴内部开发的基于 TypeScript 的 Node.js 研发框架,在集团内部,由于其集成了内部的各类基础服务与稳定性监控,同时支持 FaaS 函数部署,所以是内部 Node.js 应用研发的首选框架。

虽然 Midway 结合了面向对象(OOP + Class + IoC)与函数式(FP + Function + Hooks)两种编程范式,但考虑到一般项目大多采用面向对象的开发方式,所以本文也重点阐述针对面向对象这种范式,在工程开发中可以参考的代码设计。

基于 MVC 的工程目录设计

在 Midway 工程开发中,一般建议采用如下工作目录组织业务代码。config 目录中的代码内容,根据自身需要,结合官方的配置文档即可正确标准的完成配置,在本文中不做过多讲解。

- config  配置文件目录,存放不同环境的差异配置信息
- constant 常量存放目录,存放业务常量及国际化业务文案
- controller 控制器存放目录,存放核心业务逻辑代码
- dto 数据传输对象目录,存放外部数据的校验规则
- entity 数据实体目录,存放数据库集合对应的数据实体
- middleware 中间件目录,存放项目中间件代码
- service 服务逻辑存放目录,存放数据存储、局部通用逻辑代码
- util 工具代码存放目录,存放业务通用工具方法

当请求进入时,各目录对应的代码发挥了如下的功能作用:

  1. Middleware 作为起始逻辑进行通用性逻辑执行。
  2. 接着 DTO 层对参数进行校验。
  3. 参数校验无异常进入 Controller 执行整体业务逻辑。
  4. 数据库的调用,或者整体性比较强的通用业务逻辑会被封装到 Service 层方便复用。
  5. 工具方法、常量、配置和数据库实体则作为工程的底层支撑,向 Service 或 Controller 返回数据。
  6. Controller 吐出响应结果,如果响应异常,Middleware 进行逻辑兜底。
  7. 最终吐出响应数据返回给用户。

整理一下,你可以这么分类,在 MVC 中,C 层对应为 Middleware + DTO + ControllerM 层对应为 Service;V 层由于一般后端只提供对外的接口,不会有太多静态页面透出,所以暂时可以忽略。当然,Service 层有一定的边界混淆,它不仅仅只包含 Model 模型层,否则我们就直接起名成 Model 层好了,在 Service 中,我也会把一些可抽象、可复用的逻辑放入其中,来缓解一下复杂业务中 Controller 逻辑过于繁琐的问题。

Midway 后端代码的设计建议_第1张图片

了解上述 Midway 代码目录的设计思考后,就分别对每一个部分展开代码设计上的一些经验分享。

Middleware 层的代码建议

在开发中,业务中间件可以自行设计开发,这依赖于你的业务诉求。但是,代码执行异常,可以通过下述方案比较优雅的完成处理。

异常兜底容错中间件

代码执行异常,是指在执行业务代码过程中,可能产生的执行错误。一般来说,为了解决这种潜在的风险,我们可以在逻辑外层增加 try catch 语句进行处理。在很多工程中,由于为了做异常处理,增加了大量的 try catch 语句;还有很多工程中,没有考虑异常处理的问题,根本就没有做 try catch 的兜底容错。

// 以下代码缺少异常兜底冗错
@Get('/findOne')@Validate()
async findOne(@Query(ALL) appParams: AppFindDTO) {
  const { id } = appParams;
  const app = await this.appService.findOneAppById(id);
  return getReturnValue(true, app);
}

// 以下代码每个函数都要有一个 try catch 包裹
@Get('/findOne')@Validate()
async findOne(@Query(ALL) appParams: AppFindDTO) {
  try {
    const { id } = appParams;
    const app = await this.appService.findOneAppById(id);
    return getReturnValue(true, app);
  } catch(e) {
    return getReturnValue(false, e.message);
  }
}

使用中间件,就可以解决上面的两个问题,你可以编写如下中间件:

@Provide('errorResponse')
@Scope(ScopeEnum.Singleton)
export class ErrorResponseMiddleware {
  resolve() {
    return async (ctx: FaaSContext, next: () => Promise) => {
      try {
        await next();
      } catch (error) {
        ctx.body = getReturnValue(
          false,
          null,
          error.message || '系统发生错误,请联系管理员'
        );
      }
    };
  }
}

将这段中间件代码加入到程序的执行逻辑中,编写代码时,你就无需再关注代码执行异常的问题,中间件会帮你捕获程序执行异常并标准化返回。同时,你也可以在这里统一做异常的日志收集或实时预警,扩展更多的功能。所以这个中间件设计,强烈推荐在工程中统一使用。

DTO 层的代码建议

DTO 层,也就是数据传输对象层,在 Midway 中,主要是通过它来对 POST、GET 等请求的请求参数进行校验。在实践的过程中,有两方面的问题需要在设计中着重关注:合理的代码复用、明确的代码职责划分。

合理的代码复用

首先我们看一下不合理的 DTO 层的代码设计:

// 第一种问题:
// 分页的校验,看起来很难懂,未来很多地方都要用,这么写无法复用
export class AppsPageFindDTO {
  @Rule(RuleType.string().required())
  siteId: number;
  
  @Rule(RuleType.number().integer().empty('').default(1).greater(0))
  pageNum: number;

  @Rule(RuleType.number().integer().empty('').default(20).greater(0))
  pageSize: number;
}

// 第二种问题
// 对参数的校验,本身应该是 DTO 层面校验的,放到业务中不合理
// 同时,对逗号间隔的 id 进行校验,这是常见功能,放在这难以复用
@Get('/findMany')@Validate()
async findMany(@Query(ALL) appParams: AppsFindDTO) {
  const { ids } = appParams;
  const newIds = ids.split(',');
  if(!Array.isArray(newIds)) {
    return getReturnValue(false, null, 'ids 参数不符合要求');
  }
  const app = await this.appService.findOneAppByIds(newIds);
  return getReturnValue(true, app);
}

建议使用如下的方式进行 DTO 层的代码编写,首先对可复用的常见规则进行封装:

// 必填字符串规则
export const requiredStringRule = RuleType.string().required();
// 页码校验规则
export const pageNoRule = RuleType.number().integer().default(1).greater(0);
// 单页显示内容数量校验规则
export const pageSizeRule = RuleType.number().integer().default(20).greater(0);

// 逗号间隔的 id 进行校验的规则扩展,起名为 stringArray
RuleType.extend(joi => ({
  base: joi.array(),
  type: 'stringArray',
  coerce: value => ({
    value: value.split ? value.split(',') : value,
  }),
}));

接着在你的 DTO 定义文件中,代码就可以精简为:

// 分页的校验的逻辑可以精简为这种写法
export class AppsPageFindDTO {
  @Rule(requiredStringRule)
  siteId: number;
  @Rule(pageNoRule)
  pageNum: number;
  @Rule(pageSizeRule)
  pageSize: number;
}

// 逗号间隔的 id 字符串校验,可以改为如下写法
export class AppsFindDTO {
  @Rule(RuleType.stringArray())
  ids: number;
}

@Get('/findMany')@Validate()
async findMany(@Query(ALL) appParams: AppsFindDTO) {
    const { ids } = appParams;
    const app = await this.appService.findOneAppByIds(ids);
    return getReturnValue(true, app);
}

比起初始的代码,要精简非常多,而且所有的校验规则,都可以未来复用,这是比较推荐的 DTO 层代码设计。

明确的职责划分

DTO 的核心职责是对入参进行校验,它的职责仅限于此,但是很多时候,我们能看到这样的代码:

// Controller 层代码逻辑
@Post('/createRelatedService')
@Validate()
async createRelatedService(@Body(ALL) requestBody: AppRelationSaveDTO) {
  // 判断当前站点和应用的关联是否存在
  const appRelation = new AppRelation();
  const saveResult = await this.appServiceService.saveAppRelation(
    appRelation,
    requestBody,
  );
  return getReturnValue(true, saveResult);
}

// Service 层的代码逻辑
async saveAppRelation(
  relation: AppRelation,
  params: AppRelationSaveDTO,
) {
  const { appId, serviceId } = params;
  appId && (relation.appId = appId);
  serviceId && (relation.serviceId = serviceId);
  const result = await this.appServiceRelation.save(relation);
  return result;
}

在 Service 层中的方法中,使用了 AppRelationSaveDTO 这个 DTO 作为 Typescript 的类型来帮助做代码类型校验。这段代码问题在于,让 DTO 层承担了数据校验外的额外职责,本身 Service 层关注数据怎么存,现在 Service 层还要关注外部数据怎么传,很显然代码职责就比较混乱。

优化的方式也很简单,我们可以改进一下代码:

// Controller 层代码逻辑
@Post('/createRelatedService')
@Validate()
async createRelatedService(@Body(ALL) requestBody: AppRelationSaveDTO) {
  // 判断当前站点和应用的关联是否存在
  const { appId, serviceId } = requestBody;
  const appRelation = new AppRelation();
  const saveResult = await this.appServiceService.saveAppRelation(
    appRelation,
    appId,
    serviceId
  );
  return getReturnValue(true, saveResult);
}

// Service 层的代码逻辑
async saveAppRelation(
  relation: AppRelation,
  appId: string,
  serviceId: stirng
) {
  const { appId, serviceId } = params;
  appId && (relation.appId = appId);
  serviceId && (relation.serviceId = serviceId);
  const result = await this.appServiceRelation.save(relation);
  return result;
}

Service 层的参数类型,不再使用 DTO 进行描述,代码逻辑很清晰:Controller 层负责摘取必要数据;Service 层,负责拿到必要的数据进行增删改查即可;而 DTO 层,也只承担数据校验的职责。

控制层和服务层的代码建议

Controller 和 Service 层的设计建议可能会有比较大的争议,这里仅表达一下个人的观点:Controller 是控制器,所以业务逻辑都应该放在 Controller 中进行编写,Service 层作为服务层,应该把抽象沉淀的逻辑放在其中(比如说数据库操作,或者复用性代码)。也就是说,Controller 层应该存放业务定制的一次性逻辑,而 Service 层则存放可复用性的业务逻辑

控制层和服务层的职责明确

围绕这个思路,给一个优化代码的设计例子供参考:

// 控制器层代码
@Post('/create')
@Validate()
async update(@Body(ALL) appBody: AppSaveDTO) {
  const { code, name, description } = appBody;
  const saveResult = await this.appService.saveApp(
    code, name, description
  );
  return getReturnValue(true, saveResult);
}

// 服务层代码
async saveApp(code: sting, name: string, description: string) {
  const app = await this.findOneAppByCode(code);
  app.code = code;
  app.name = name;
  app.description = description;
  const result = await this.appModel.save(app);
  return result;
}

这段代码,其实是要更新一条信息,而且一下子必须更新 code,name 和 description,这样做 Service 层其实是和 Controller 有耦合的,到底怎么存实际上是业务逻辑,应该由 Controller 来决定,所以建议修改成如下代码:

// 控制器层代码
@Post('/create')
@Validate()
async update(@Body(ALL) appBody: AppSaveDTO) {
  const { code, name, description } = appBody;
  const app = await this.appService.findOneAppByCode(code);
  app.code = code;
  app.name = name;
  app.description = description;
  const saveResult = await this.appService.saveApp(app);
  return getReturnValue(true, saveResult);
}

// 服务层代码
async saveApp(app: App) {
  const result = await this.appModel.save(app);
  return result;
}

这样写,相对于之前的代码,Controller 更聚焦业务;Service 更聚焦服务,而且能够得到更好的复用。这是在控制器和服务层写代码时可以参考的设计思路。

控制器层和服务层一对一匹配

在编写 Midway 代码的时候,存在这样的一种灵活性:控制器可以调用多个服务,而服务之间也可以互相调用。也就是说,服务层的一段代码,可能在任何的控制器中被调用,也可能在任何的服务层被调用。这种比较强的灵活度,最终一定会导致代码的层次结构不清晰,编码方式不统一,最终导致系统可维护性减弱。

为了规避过度灵活可能带来的问题,我们可以从规范上进行一定的约束。目前我的想法是,控制器只调用自己的服务层,如果需要其他服务层的能力,在自己的服务层进行转发。这样做后,一个服务层的代码,只能被自己的控制器调用,或者被其他的服务层调用,调用的灵活度从 N2 降低到 N,代码也就相对更可控。

依然通过代码举例来说:

// 控制器中的函数方法
@Post('/create')
@Validate()
async create(@Body(ALL) siteBody: SiteCreateDTO) {
  // 用到一个 ACL 的服务层
  const hasPermission = await this.aclService.checkManagePermission('site');
  if (!hasPermission) {
    return getReturnValue(false, null, '您无权限,无法创建');
  }
  const { name, code } = siteBody;
  const site = new Site();
  site.name = name;
  site.code = code;
  // 用到自身的服务层
  const result = await this.siteService.createSite(site);
  return getReturnValue(true, result);
}

如果代码这样设计,业务代码中,用到 ACL 的服务,校验权限,那么随着业务的发展,aclService 层可能会耦合越来越多的定制逻辑,因为所有的权限校验都由着一个方法提供,如果调用场景多,肯定会存在定制化需求。

所以更合理、更可扩展的代码可以改变成下面的样子:

// 控制器中的函数方法
@Post('/create')
@Validate()
async create(@Body(ALL) siteBody: SiteCreateDTO) {
  // 用到自身的服务层
  const hasPermission = await this.siteService.checkManagePermission();
  if (!hasPermission) {
    return getReturnValue(false, null, '您无权限,无法创建');
  }
  const { name, code } = siteBody;
  const site = new Site();
  site.name = name;
  site.code = code;
  // 用到自身的服务层
  const result = await this.siteService.createSite(site);
  return getReturnValue(true, result);
}

// 自身服务层的代码
async checkManagePermission(): Promise {
  const hasPermission = await this.aclService.checkUserPermission('site');
  return hasPermission;
}

在自身的服务层,增加一层转发代码,不仅可以约束代码的灵活度,当定制性逻辑增加的时候,也可以直接在这里扩展,所以是一种更合理的代码设计。

数据库查询的代码设计

使用逻辑表关联

在 Midway 中,集成的 TypeORM 的数据库框架,里面提供了 OneToOne ,OneToMany 这样的数据库操作语法,帮助你自动生成 Join 语句,管理表之间的关联。

但在业务系统中,我不建议使用这种直接的表连接语句,因为这很容易产生慢 SQL,影响系统的性能,所以建议在数据库操作中,统一采用逻辑表关联的方式进行关联数据查询,这里直接给出代码例子:

@Get('/findRelatedServices')
  @Validate()
  async findRelatedServices(@Query(ALL) appParams: AppServicesFindDTO) {
    const { id } = appParams;
    // 寻找关联关系内容
    const relations = await this.appService.findAppRelatedServices(id);
    // 从关联关系中找到另一张表关联的 id 合集
    const serviceIds = relations.map(item => item.serviceId);
    // 去另一张表取数据拼装
    const services = await this.appService.findServicesByIds(serviceIds);
    // 返回最终数据
    return getReturnValue(true, {services});
  }

虽然这种查询,相对于 Join,代码更多,但是逻辑全部在代码中体现,而且性能很好,所以在开发中,推荐使用这种数据库操作的设计。

常量的用法

常量在服务端开发中非常常用,通过常量语义化的表述一些枚举,这种基础内容不再累述,主要讲一下使用常量管理业务提示的想法。

业务提示文案抽离

复杂的项目,最终有可能走向国际化的路线,如果在代码中,写死的文字提示太多,最后做国际化,还是要投入精力修改,所以不如在开发开始,就对项目做一个提前准备,很简单,你只要把所有的文字提示抽离到常量文件里管理就可以了。

// 不推荐这种写法,文字和业务耦合
@Post('/create')
@Validate()
async create(@Body(ALL) appBody: AppSaveDTO) {
  const { code, name } = appBody;
  const appWithSameCode = await this.appService.findOneAppByCode(code);
  if (appWithSameCode) {
    // 文字和业务耦合在一起
    return getReturnValue(false, null, 'code 已存在,无法重复创建!');
  }
  const app = new App();
  const saveResult = await this.appService.saveApp(app, name);
  return getReturnValue(true, saveResult);
}

// 推荐这种写法,文字和业务解耦
@Post('/create')
@Validate()
async create(@Body(ALL) appBody: AppSaveDTO) {
  const { code, name } = appBody;
  const appWithSameCode = await this.appService.findOneAppByCode(code);
  if (appWithSameCode) {
    // 文字拆离到常量中管理,实现解耦
    return getReturnValue(false, null, APP_MESSAGES.CODE_EXIST);
  }
  const app = new App();
  const saveResult = await this.appService.saveApp(app, name);
  return getReturnValue(true, saveResult);
}

很小的一个改动,就可以让你的代码看起来有很大的变化,非常建议使用这个技巧。

总结

在复杂的项目开发中,选择好开发框架只是第一步,真正把代码写好才是最困难的事情,本篇文章总结了过去一年在使用 Midway 框架开发过程中,我对如何写好服务端代码自己的一些思考和编码技巧,希望能够对你有一定的启发,如果有挑战获疑问,欢迎留言讨论。

作者:ES2049 | Dell

文章可随意转载,但请保留原文链接。
非常欢迎有激情的你加入 ES2049 Studio,简历请发送至 [email protected]

你可能感兴趣的:(前端接口设计微服务)