前言

本篇：通过编写一个 HelloWorld 应用，串一下后端开发流程。

初始化项目

这里我们可以通过官方指引完成项目初始化和启动，我们按官网脚手架初始化生成项目，执行 npm run dev 启动应用即可（自带代码更新重启）。

略略略。

项目结构

我们只关注 ./src 目录下的内容，里面包括文件如下：

./src
├── config                // 配置文件目录
│   ├── config.default.ts
│   └── config.unittest.ts
├── configuration.ts      // 应用入口文件
├── controller            // 控制器目录，管理路由
│   ├── api.controller.ts
│   └── home.controller.ts
├── filter                // 过滤器目录，先不看
│   ├── default.filter.ts
│   └── notfound.filter.ts
├── interface.ts          // 全局TS类型定义文件
├── middleware            // 中间件目录，先不看
│   └── report.middleware.ts
└── service               // 服务目录，编写CRUD逻辑
    └── user.service.ts

HelloWord 实战

这里按照个人的开发习惯重组一下代码，借此大家可以更深入了解下 Midway 项目大致组织结构，也方便后续教程进行。

这里推荐大家使用 VsCode 编辑器进行开发。

修改配置

koa 里的配置对象是基于约定的，最终会传给底层依赖的 Koa 框架。我们可以尝试修改，看看效果。

1. 端口号

找到 ./src/config/config.default.ts 文件，修改端口号 7001 为 8080 或者其他。

2. 全局路由前缀

同样，可以添加 globalPrefix 字段设置全局路由的前缀。

// ./src/config/config.default.ts
import { MidwayConfig } from '@midwayjs/core';

export default {
  // use for cookie sign key, should change to your own and keep security
  keys: '1675590443187_6035',
  koa: {
    port: 8080,
    globalPrefix: "/api",
  },
} as MidwayConfig;

之后只要请求服务，所有的路由都要加上 api 前缀。

这里推荐大家使用 ApiFox 进行API请求和调试。

新增模块

关于目录结构，个人习惯于以目录的形式聚合相关联 controller 和 service，方便聚焦管理和查找。

Controller 主要负责路由的管理以及入参出参的校验
Service 主要负责业务逻辑和 CRUD。两者需要划分边界，以此开后续代码的可维护性

这里我们以创建 get_user（根据 id 获取用户信息） API 为例。

1. 新增 Service

新增 ./src/modules/user 目录，在 user 目录下创建 user.service.ts 文件。

import { Provide } from '@midwayjs/decorator';

@Provide()
export class UserService {
  async get(uid: string) {
    if (!uid) return null;

    // mock 数据库查询返回数据
    return {
      uid: uid,
      username: '不败花',
      phone: '12345678901',
      email: 'xxxxxx@xxx.com',
    };
  }
}

2. 新增 Controller

再在 user 目录下创建 user.controller.ts 文件。请求API路径为 /api/user/get_user。

import { Controller, Get, Inject, Query } from '@midwayjs/decorator';
import { UserService } from './user.service';

// 路由
@Controller('/user')
export class UserController {
  @Inject()
  userService: UserService;

  @Get('/get_user')
  async getUser(@Query('uid') uid) {
    const user = await this.userService.get(uid);

    if (!user) return { code: 6000, msg: 'User not found', data: null };

    return { code: 0, msg: 'OK', data: user };
  }
}

@Get 表示以 GET 方式接收请求，通过 @Query('uid') 来获取请求查询参数 uid。

最后，我们用 Apifox 测试验证一下请求，传入任意请求参数 uid。

可以看到，API 请求是可以成功的。这里我们并没有使用将 UserController 在任何地方配置引入，路由就可以生效。这是因为我们通过 @Controller('/user') 实现了路由注册，MidwayJS 默认在 src 目录下 @Controller 声明的都会被注册为 API 路由，最终生效。这点可能和 NestJS 不大相同（需要最终在根模块上声明）。

小结

至此，对于获取用户的 API，我们的整个开发流程已经完成的七七八八了。

可以看到，对于搬砖工作，主要还是集中在 Service 和 Controller 里面，所以我更倾向于聚合在一个文件夹下面，不至于太乱。

响应结构一致性

对于 Rest API 的响应体设计，我们可以看到，大多数是和前端约定好的统一的数据结构，这样前端对接可以做相应的逻辑处理；同时，约定统一的接口响应规范也可以减少重复编码，提高团队整体效率。

值得一提的是，团队基于此可以做很多事情，比如埋点统一读取字段上报统计分析、接口文档统一导出、请求库统一封装等等。

{ code: number, msg: string, data: any }

1. 新增辅助类

这里我们后端一般会抽象一个工具类来实现响应结构统一，以后都可以使用这个辅助类进行接口出参处理。

// ./src/utils/index.ts
export class BaseResponse<T> {
  code: number;
  msg: string;
  data: T;

  constructor(data: T, code: number, msg: string) {
    this.code = code;
    this.msg = msg;
    this.data = data;
  }

  static create<T>(data: T, code: number, msg: string) {
    return new BaseResponse(data, code, msg);
  }

  static ok<T>(data: T) {
    return BaseResponse.create(data, 0, 'OK');
  }

  static error(msg: string, code: number) {
    return BaseResponse.create(null, code, msg);
  }
}

2. BaseResponse 改造

然后，我们回到 user.service.ts 进行一波改造，这样就可以愉快的玩耍啦。

import { Controller, Get, Inject, Query } from '@midwayjs/decorator';
+ import { BaseResponse } from '../../utils';
import { UserService } from './user.service';

// 路由
@Controller('/user')
export class AppController {
  @Inject()
  userService: UserService;

  @Get('/get_user')
  async getUser(@Query('uid') uid) {
    const user = await this.userService.get(uid);

-   if (!user) return { code: 6000, msg: 'User not found', data: null };
+    if (!user) return BaseResponse.error('User not found', 6000);

-    return { code: 0, msg: 'OK', data: user };
+    return BaseResponse.ok(user);
  }
}