Skip to content

9. 案例研究:NestJS 中的税额计算服务器

Image

9.1. 需求回顾

要移植的服务器是一个所得税计算服务器(PHP)(参见 通过示例介绍 PHP7 语言),采用分层架构(Config / Entities / Model-DAO-Business / Controllers / Responses / Views),带有一个前端控制器(main.php),它根据动作把传入的请求——所有请求都采用 URL 形式(main.php?action=...)——路由到相应的控制器。移植的目标是在 NestJS 中原样保留这种 MVC 架构,逐个动作、逐个状态码地保留,从而使其仍然与已经为 PHP 服务器编写的 HTML/TypeScript 客户端兼容。

9.2. MVC 架构得以沿用

两个服务器之间的对应关系是直接的:

  • Config/config.json ↔ ConfigService;
  • Entities/*.php ↔ entities/*.entity.ts (TaxAdminData、Simulation);
  • Model/ServerDao*.php ↔ ServerDaoService ([DAO] 层,第 5 章);
  • Model/ServerBusiness.php ↔ ServerBusinessService([business] 层,逐行对应);
  • Controllers/*Controller.php (每个动作一个)↔ 每个 TypeScript 类对应一个动作控制器,由注册表动态选择(ActionsRegistryService);
  • Responses/*Response.php ↔ ResponseSenderService (jSON、XML)和 HtmlViewRendererService(HTML);
  • Views/*.php ↔ EJS 模板(views/*.ejs),采用相同的 Bootstrap 布局。
注意:此服务器上的所有动作都经过同一个路由,即 http://localhost:3000/main.php;所请求动作的名称始终作为查询字符串参数 ?action=action-name提供——绝不出现在 URL 路径中。这是一种刻意的 URL 设计,与前几章的示例(动作 [/a01]、[/m01]……按路径片段路由)不同,这里完全保持原 PHP 服务器上的样子,以便与已经编写好的客户端保持兼容。

9.3. 项目文件结构

在详细介绍每一层之前,下面是 nestjs-case-study 项目的完整目录结构,即在运行 npm install 之后的样子(dist/ 文件夹由 npm run build 生成,它和 node\_modules/ 目录 均未显示):

nestjs-case-study/
+-- .env.example
+-- .gitignore
+-- README.md
+-- create_dbtaxes.sql
+-- nest-cli.json
+-- package.json
+-- tsconfig.json
+-- tsconfig.build.json
+-- data/
| +-- tax-admin-data.json
+-- Logs/
+-- public/
| +-- Resources/
| +-- logo.jpg
+-- views/
| +-- view-authentication.ejs
| +-- view-tax-calculation.ejs
| +-- view-simulations-list.ejs
| +-- view-errors.ejs
| +-- partials/
| +-- banner.ejs
| +-- menu.ejs
| +-- authentication-form.ejs
| +-- tax-calculation-form.ejs
| +-- simulations-list-table.ejs
+-- src/
    +-- main.ts
    +-- app.module.ts
    +-- main.controller.ts
    +-- config/
    | +-- config.service.ts
    +-- entities/
    | +-- simulation.entity.ts
    | +-- tax-admin-data.entity.ts
    | +-- tax-exception.ts
    +-- model/
    | +-- server-dao.interface.ts
    | +-- server-dao.service.ts
    | +-- server-business.service.ts
    +-- actions/
    | +-- action-controller.interface.ts
    | +-- actions-registry.service.ts
    | +-- init-session.controller.ts
    | +-- authenticate-user.controller.ts
    | +-- calculate-tax.controller.ts
    | +-- display-tax-calculation.controller.ts
    | +-- list-simulations.controller.ts
    | +-- delete-simulation.controller.ts
    | +-- end-session.controller.ts
    | +-- admin-data.controller.ts
    +-- responses/
    | +-- response-sender.service.ts
    +-- views/
    | +-- view-models.ts
    | +-- html-view-renderer.service.ts
    +-- session/
    | +-- session.types.ts
    +-- utilities/
    | +-- logger.service.ts
    +-- filters/ (reserved, currently empty)

各元素的作用:

  • .env / .env.example —— 环境变量(端口、会话密钥、MySQL 及 TAX_DATA_SOURCE 参数等),由 ConfigService 读取;.env 不纳入版本控制(.gitignore);.env.example 用作要复制的模板(cp .env.example .env);
  • .gitignore —— 排除 node_modules/、dist/、.env、以及仓库中的日志;
  • README.md —— 项目文档(安装、PHP 与 NestJS 之间的对应关系、带注释的目录结构):本章对其内容进行了总结和扩展;
  • create_dbtaxes.sql —— 创建 MySQL dbtaxes-2019 数据库的脚本(表 tbbrackets、tbconstants……,仅在 TAX_DATA_SOURCE=mysql 时使用);
  • nest-cli.json、tsconfig.json、tsconfig.build.json —— CLI、NestJS 和 TypeScript 编译器的配置,前几章已经讨论过;
  • package.json —— 依赖(ejs、express-session、mysql2、js2xmlparser、dotenv……)和 npm 脚本(start、start:dev、build);
  • data/tax-admin-data.json —— 备用税务数据集,在 TAX_DATA_SOURCE=json 时使用:测试服务器无需安装 MySQL;
  • Logs/ —— 应用日志目录(logs.txt),由 LoggerService 写入;如果启动时尚不存在,则会自动创建;
  • public/Resources/logo.jpg —— 静态图片,由 app.useStaticAssets(...) 在 main.ts 中原样提供,用于 HTML 视图中的横幅;
  • views/ (位于项目根目录)—— EJS 模板及其局部模板,详见下文的“构建 HTML 页面”;
  • src/main.ts —— 入口点:启动 NestJS 服务器(见下文);
  • src/app.module.ts —— 根模块:将 MainController 声明为唯一的控制器,并声明应用的所有提供者;
  • src/main.controller.ts —— 前端控制器,上文已经描述;
  • src/config/ —— 应用配置(ConfigService),详见下文;
  • src/entities/ —— 数据类(Simulation、TaxAdminData、TaxException),详见下文;
  • src/model/ —— [DAO] 层和 [business] 层;
  • src/actions/ —— 每个动作一个控制器、公共接口 ActionController、以及注册表 ActionsRegistryService;
  • src/responses/ —— 响应生成(jSON/XML)和 CORS 处理(ResponseSenderService);
  • src/views/ —— 注意:不要把它与 根目录中的 views/ 目录混淆。此文件夹只包含 TypeScript,即显示模板的构造(view-models.ts)以及视图(EJS)的选择/渲染(html-view-renderer.service.ts);
  • src/session/ —— Express 会话的 TypeScript 类型定义(session.types.ts);
  • src/utilities/ —— 日志记录(LoggerService);
  • src/filters/ —— 预留目录,目前为空:在此版本的项目中尚未使用。

有两个文件值得进一步说明:src/main.ts 和 src/app.module.ts,它们都是本项目特有的(超出前几章已经介绍过的框架内容)。摘自 src/main.ts:

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);

  app.useStaticAssets(join(process.cwd(), 'public'));

  app.use(
    session({
      secret: process.env.SESSION_SECRET ?? 'change-me-in-production',
      resave: false,
      saveUninitialized: false,
      cookie: { httpOnly: true, sameSite: 'lax', secure: false, path: '/' },
    }),
  );

  const port = Number(process.env.PORT ?? 3000);
  await app.listen(port);
}

我们来解读这段代码:

  • 第 4 行:app.useStaticAssets(join(process.cwd(), 'public')); —— 通过静态路由原样提供 public/ 文件夹中的文件(这里是 public/Resources/logo.jpg),而不经过 NestJS 控制器;
  • 第 6 行:app.use(session({...})); —— 直接在 NestJS 应用上安装 express-session 中间件:app.use(...) 在这里的工作方式与普通 Express 应用完全相同,因为 NestJS 构建在 Express 之上——这正是 request.session 在 MainController 和每个动作控制器中有意义的原因;
  • 第 13 行:const port = Number(process.env.PORT ?? 3000); —— 监听端口与其余可配置的设置一样,来自环境变量(位于 .env 文件中),默认值为 3000 。

src/app.module.ts 是根模块(前几章已经遇到过):它将 MainController 声明为唯一的控制器,并在其 providers 数组中列出应用的所有提供者——这些服务(ConfigService、LoggerService、ServerDaoService、ServerBusinessService、ResponseSenderService、HtmlViewRendererService、ActionsRegistryService)和八个动作控制器,它们都可以通过这同一个依赖注入机制相互注入。

9.4. 前端控制器

一个单独的控制器(NestJS 中的 MainController)接收所有发往 /main.php?action=...(@All('main.php'))的请求:它获取 action 参数,检查所有动作共有的前置条件(动作已知、会话已初始化、用户已通过身份验证),然后委托给相应动作的控制器。

摘自 src/main.controller.ts:

@Controller()
export class MainController {
  constructor(
    private readonly configService: ConfigService,
    private readonly responseSender: ResponseSenderService,
    private readonly actionsRegistry: ActionsRegistryService,
  ) {}

  @All('main.php')
  async handle(@Req() request: Request, @Res() response: Response): Promise<void> {
    const action = String(request.query.action ?? '').toLowerCase();

    if (!this.actionsRegistry.has(action)) {
      // ……状态 102:无效的动作
    }
    if (!request.session.type && action !== 'init-session') {
      // ……状态 103:没有正在进行的会话
    }
    if (!request.session.user && action !== 'authenticate-user' && action !== 'init-session') {
      // ……状态 104:用户未通过身份验证
    }

    const controller = this.actionsRegistry.get(action);
    const result = await controller.execute(config, request, request.session);
    // ……构建并发送响应(§6.7)
  }
}

我们来解读这段代码:

  • 第 1 行:[@Controller()] —— 此装饰器将该类标记为 NestJS 控制器 -- 这里不带参数使用,它不设置任何公共前缀:确切的前缀由下面方法本身上指定的路由来决定;
  • 第 3 行:[constructor(...)] —— 通过构造函数注入三个 @Injectable() 提供者:配置服务、响应发送服务和动作注册表 -- NestJS 会自动实例化并提供它们,无需在任何地方编写 new ConfigService() ;
  • 第 9 行:[@All('main.php')] —— @All 是一个路由装饰器,它将其后的方法与给定 URL 的所有 HTTP 方法(GET、POST、PUT、DELETE……)关联起来——这里的 URL 是 /main.php(这个沿用自 PHP 服务器的名称,在 NestJS 中仅表示 URL 路径,而不是实际被执行的 PHP 文件);正是这一点使得同一个控制器只需声明一个路由,就能同时处理读取类动作(GET,例如 init-session)和提交数据的动作(POST,例如 calculate-tax);
  • 第 10 行:[@Req() request: Request, @Res() response: Response] —— 两个我们已经见过的参数装饰器:@Req() 注入完整的请求对象(HTTP 方法、请求头、query、body、会话等),而 @Res() 注入 Express 响应对象,从而完全控制返回的内容——这里之所以必要,是因为该控制器必须根据情况自行选择 HTTP 状态码和响应格式(jSON、XML 或 HTML),而简单的 return 语句无法做到如此精确;
  • 第 11 行:[const action = String(request.query.action ?? '').toLowerCase();] —— action 参数是从 手动读取自 request.query 的——因为我们选择了 @Req() ,而不是上一章中见过的 @Query('action') 装饰器,所以代码必须自己从请求对象中获取该值;
  • 第 21 行:[const controller = this.actionsRegistry.get(action);] —— 在前置条件验证通过后,MainController 并不亲自处理该动作:它根据动作名称找到对应的动作控制器(见下一节),并将工作委托给它。
注意:此控制器使用 @Req() 和 @Res() ,而不是上一章中的各个单独装饰器(@Query()、@Body()等):它需要完整访问请求(方法、所有参数),并完全控制所发送的响应(状态码和格式的选择)——这与 main.php 借助 Symfony 的 Request 和 Response 对象所做的完全一样。

9.5. 动作控制器

每个动作都有自己的控制器,这些控制器实现一个公共接口 ActionController——它是 PHP 中 InterfaceController 接口的 TypeScript 对应物。下面是 [calculate-tax] 动作控制器的简化版本:

摘自 src/actions/calculate-tax.controller.ts:

@Injectable()
export class CalculateTaxController implements ActionController {
  constructor(
    private readonly dao: ServerDaoService,
    private readonly business: ServerBusinessService,
  ) {}

  async execute(config, request, session): Promise<ActionResult> {
    // ……验证提交的参数 [married, children, salary]
    // (与原 PHP 控制器相同的数字状态码)

    const taxAdminData = await this.dao.getTaxAdminData();
    const result = this.business.calculateTax(married, children, salary, taxAdminData);

    const simulations = session.simulations ?? [];
    simulations.push(Simulation.fromAttributes({ married, children, salary, ...result }));
    session.simulations = simulations;

    return { statusCode: 200, status: 300, content: { response: result }, headers: {} };
  }
}

我们来拆解这段代码:

  • 第 1 行:[@Injectable()] —— 这里要注意的第一个重要点:CalculateTaxController 是一个普通的提供者(@Injectable()),而不是NestJS 控制器——它既没有 @Controller() 也没有任何路由(@Get、@Post……);只有 MainController (见上文)才会被 NestJS 的 HTTP 路由器识别;
  • 第 2 行:[export class CalculateTaxController implements ActionController] —— 该类实现了项目自定义的接口 ActionController (定义于 action-controller.interface.ts),该接口只要求一个方法:execute(...) -- 这是项目约定,而不是 NestJS 的机制;
  • 第 3 行:[constructor(...)] —— 通过构造函数注入两个服务:DAO ([DAO] 层,访问税务数据)和业务逻辑 ([business] 层,纯计算);
  • 第 8 行:[async execute(config, request, session): Promise<ActionResult>] —— 由 MainController.handle() (controller.execute(...),见上文)调用的方法 -- 它的参数不是 NestJS 装饰器(@Body()、@Session()等),因为这个方法从不由 HTTP 路由器直接调用:MainController 已经手动把它通过 @Req() 自己接收到的请求和会话传给了它;
  • 第 12 行:[const taxAdminData = await this.dao.getTaxAdminData();] —— 通过上一章介绍的 [DAO] 层,获取计算所需的税务数据(税率档次、阈值);
  • 第 19 行:[return { statusCode: 200, status: 300, content: { response: result }, headers: {} };] —— 第二个重要点:execute() 返回的内容并不会原样发送给浏览器——它是项目自定义的结构 ActionResult(statusCode、status、content、headers),由 MainController 解析,然后传给 ResponseSenderService,由后者构造实际发送的 HTTP 响应(根据会话类型为 jSON、XML 或 HTML——见下文)。

此动作由向 http://localhost:3000/main.php?action=calculate-tax 发出的 POST 请求触发,三个参数“married”、“children”和 “salary” 包含在请求体中(而不在 URL 中)——事实上,这正是 execute() 检查的第一件事,甚至先于读取这些参数。

9.6. 其他动作控制器

每个动作都有自己的控制器,它们都实现同一个接口(PHP 中 InterfaceController 接口的 TypeScript 对应物)——摘自 src/actions/action-controller.interface.ts:

export interface ActionResult {
  statusCode: number;
  status: number;
  content: Record<string, unknown>;
  headers: Record<string, string>;
}

export interface ActionController {
  execute(config: AppConfig, request: Request, session: AppSession): Promise<ActionResult>;
}

并且都通过一个注册表按其动作名称进行标识,该注册表本身由构造函数注入到 MainController 中——摘自 src/actions/actions-registry.service.ts:

  constructor(
    initSession: InitSessionController,
    authenticateUser: AuthenticateUserController,
    calculateTax: CalculateTaxController,
    listSimulations: ListSimulationsController,
    deleteSimulation: DeleteSimulationController,
    endSession: EndSessionController,
    displayTaxCalculation: DisplayTaxCalculationController,
    adminData: AdminDataController,
  ) {
    this.registry = {
      'init-session': initSession,
      'authenticate-user': authenticateUser,
      'calculate-tax': calculateTax,
      'list-simulations': listSimulations,
      'delete-simulation': deleteSimulation,
      'end-session': endSession,
      'display-tax-calculation': displayTaxCalculation,
      'get-admindata': adminData,
    };
  }

我们来拆解这段代码:

  • NestJS 实例化八个动作控制器中的每一个(借助 @Injectable()),并把它们全部以构造完成的状态传给 ActionsRegistryService 的构造函数——后者只是把它们存储在一个以动作名称为索引的关联数组中;
  • 这个表(this.registry)的作用与 PHP 端 [actions] 在 Config/config.json 中的表完全相同,但无需手动实例化任何东西:has(action) 和 get(action) 是 MainController 唯一使用的两个方法。

[calculate-tax] 动作已在上文中详细描述。以下是其他七个动作控制器各自的特点:

  • init-session.controller.ts —— 初始化会话的响应类型(session.type = json、html、或 xml);必须是第一个被调用的动作(它是唯一被 MainController 豁免“当前无会话”检查的动作);要求使用 GET 方法,且请求参数恰好为两个(action、type);
  • authenticate-user.controller.ts —— 将提交的 登录名/密码 组合与 config.users 中的列表进行核对;通过累加错误位来构造其状态码(status += 2 表示 用户名 缺失,status += 4 表示 密码 缺失)——与原 PHP 验证器的数值逻辑相同;
  • list-simulations.controller.ts —— 其中最简单的一个:返回 session.simulations ?? [],不做任何计算;
  • delete-simulation.controller.ts —— 执行一系列检查(方法/参数个数、“number” 参数是否存在、数字语法、索引是否在数组范围内),每成功一步就逐位累加状态码,然后调用 simulations.splice(number, 1) 并将数组重新保存到会话中;
  • display-tax-calculation.controller.ts —— 比 list-simulations 还要简短:除了返回状态码 800外什么也不做,这样客户端无需任何服务器端处理,就能直接切换到另一个视图(返回计算表单);
  • admin-data.controller.ts —— 直接委托给 ServerDaoService.getTaxAdminData() 并拦截 TaxException 以返回错误状态 1041;与 calculate-tax 一起,它是仅有的两个在构造函数中注入 [DAO] 层的动作控制器;

src/actions/end-session.controller.ts 的情况因一个经典的 Express-Session 陷阱而值得更仔细地研究:

async execute(config: AppConfig, request: Request, session: AppSession): Promise<ActionResult> {
  const method = request.method.toLowerCase();
  const nbParams = Object.keys(request.query).length;
  if (method !== 'get' || nbParams !== 1) {
    return {
      statusCode: 400,
      status: 401,
      content: { response: "GET required with the single parameter [action] in the URL" },
      headers: {},
    };
  }
  const type = session.type;
  await new Promise<void>((resolve) => session.regenerate(() => resolve()));
  request.session.type = type;
  return {
    statusCode: 200,
    status: 400,
    content: { response: 'session deleted' },
    headers: {},
  };
}

我们来解读这段代码:

  • 第 9 行:const type = session.type; —— 我们在销毁会话之前先保存响应类型(json/html/xml),因为需要在新会话中恢复它;
  • 第 10 行:await new Promise<void>((resolve) => session.regenerate(() => resolve())); —— 该控制器中一个棘手的地方:session.regenerate(callback) 由 express-session 提供,是一个回调式方法,而不是 Promise;因此我们把它包装在一个 Promise 中,以便像其余代码一样对它使用 await;regenerate() 会清除当前会话并为其分配一个全新的标识符(相当于 Symfony 中的会话销毁);
  • 第 11 行:request.session.type = type; —— 第二个棘手的点:在 regenerate() 之后,request.session 指向一个全新的会话实例;在调用会话之前,旧的引用已被捕获到 execute() 参数中,现在已成为孤立引用——这就是为什么要把类型重新赋给 request.session 而不是 session;否则它会悄无声息地丢失。

9.7. [DAO] 层

ServerDaoService(§5.1)向业务层提供税务数据(税率档次、阈值),数据来源取决于某个配置参数,可以是 jSON 文件(便于在没有数据库的情况下测试),也可以是使用 mysql2 访问的 MySQL。

摘自 src/model/server-dao.interface.ts——一份最小契约,即 [DAO] 层的每个实现都必须提供的唯一方法:

1
2
3
export interface IServerDao {
  getTaxAdminData(): Promise<TaxAdminData>;
}

摘自 src/model/server-dao.service.ts,这是本项目中该契约的唯一实现:

@Injectable()
export class ServerDaoService implements IServerDao {
  constructor(private readonly configService: ConfigService) {}

  async getTaxAdminData(): Promise<TaxAdminData> {
    const { taxDataSource } = this.configService.config;
    if (taxDataSource === 'mysql') {
      return this.getTaxAdminDataFromMysql();
    }
    return this.getTaxAdminDataFromJson();
  }

  private async getTaxAdminDataFromJson(): Promise<TaxAdminData> {
    const { jsonTaxDataFile } = this.configService.config;
    try {
      const fileContents = fs.readFileSync(jsonTaxDataFile, 'utf-8');
      const attributes = JSON.parse(fileContents);
      return TaxAdminData.fromAttributes(attributes);
    } catch (ex) {
      throw new TaxException(
        `The tax data file [${jsonTaxDataFile}] could not be processed: ${(ex as Error).message}`,
      );
    }
  }

  private async getTaxAdminDataFromMysql(): Promise<TaxAdminData> {
    const { mysql: dbConfig } = this.configService.config;
    let connection: mysql.Connection | null = null;
    try {
      connection = await mysql.createConnection({
        host: dbConfig.host,
        port: dbConfig.port,
        database: dbConfig.database,
        user: dbConfig.user,
        password: dbConfig.password,
      });

      // 税率档次(表 tbbrackets)
      const [brackets] = await connection.query<RowDataPacket[]>(
        'select limits, coeffR, coeffN from tbbrackets order by id',
      );
      const limits = brackets.map((row) => Number(row.limits));
      const coeffR = brackets.map((row) => Number(row.coeffR));
      const coeffN = brackets.map((row) => Number(row.coeffN));

      // 计算常量(表 tbconstants)
      const [constantsRows] = await connection.query<RowDataPacket[]>(
        'select halfShareQfCeiling, ... from tbconstants limit 1',
      );
      const row = constantsRows[0];

      return TaxAdminData.fromAttributes({
        limits, coeffR, coeffN,
        halfShareQfCeiling: Number(row.halfShareQfCeiling),
        // ……其余八个常量也进行相同的 Number(...) 转换
        // (完整列表参见源文件)
      });
    } catch (ex) {
      throw new TaxException(`[mysql] ${(ex as Error).message}`);
    } finally {
      if (connection) {
        await connection.end();
      }
    }
  }
}

我们来解读这段代码:

  • async getTaxAdminData(): Promise<TaxAdminData> { if (taxDataSource === 'mysql') ... } —— 决策过程只需一行:根据 config.taxDataSource (读取自环境变量 TAX_DATA_SOURCE),数据从 jSON 文件或 MySQL 中获取,但暴露给应用其余部分的契约(IServerDao)保持不变——CalculateTaxController 和 AdminDataController 并不知道实际使用的是哪个数据源;
  • getTaxAdminDataFromJson() —— 同步读取并解析 data/tax-admin-data.json (fs.readFileSync);任何错误(文件缺失、jSON 无效)都会被拦截,并以带有明确消息的 TaxException 形式记录下来——绝不会是原始的 Node 异常,因为那种异常无法被正确地传播回客户端;
  • getTaxAdminDataFromMysql() —— 使用 每次调用时都打开 一个 MySQL 连接,借助 mysql2/promise (不复用连接池:与 README 中提到的没有 Redis 缓存一致,每次查询都会重新检查所有内容);执行两条 SQL 查询(税率档次,然后是常量),根据检索到的行重建一个 TaxAdminData ,并且无论读取是否成功,都会在 finally 块中系统地关闭连接;
  • 两个私有方法返回相同的类型(Promise<TaxAdminData>),这使得 getTaxAdminData() 可以保持为一个简单的外观,自身不含任何业务逻辑。

9.8. [business] 层

ServerBusinessService 不了解 HTTP、会话或数据库:它是 PHP 服务器中税额计算的逐行移植,纯粹且可独立于其余部分进行测试。

摘自 src/model/server-business.service.ts:

@Injectable()
export class ServerBusinessService {
  calculateTax(
    married: string,
    children: number,
    salary: number,
    taxAdminData: TaxAdminData,
  ): TaxCalculationResult {
    // ……与 Model/ServerBusiness.php 相同的算法:家庭商数、
    // 封顶、减税、减免
  }

  private getTaxableIncome(salary: number, taxAdminData: TaxAdminData): number {
    let allowance = 0.1 * salary;
    if (allowance > taxAdminData.tenPercentAllowanceMax) {
      allowance = taxAdminData.tenPercentAllowanceMax;
    }
    if (allowance < taxAdminData.tenPercentAllowanceMin) {
      allowance = taxAdminData.tenPercentAllowanceMin;
    }
    return Math.floor(salary - allowance);
  }
}
  • 第 1 行:[@Injectable()] —— 又是同一个装饰器,原因与本章其他地方相同:没有它,NestJS 就无法实例化 ServerBusinessService ,也无法将其注入到上面的 CalculateTaxController 中;
  • 第 2 行:[export class ServerBusinessService {] —— 从这里开始,除了第一个装饰器之外,代码不再特定于 NestJS:calculateTax(...) 和 getTaxableIncome(...) 都是标准的 TypeScript 代码——对 PHP 算法的逐行移植,不涉及 HTTP 或数据库。

9.9. 应用程序配置

src/config/config.service.ts 把原先在 PHP 端分散于 Config/config.json 和 Config/database.json 中的内容合并到了单个 NestJS 服务中——但有一个预期的差别:敏感配置(密码、会话密钥)现在来自环境变量(.env 文件),而不是纳入版本控制的 jSON 文件:

@Injectable()
export class ConfigService {
  readonly config: AppConfig;

  constructor() {
    this.config = {
      corsAllowed: (process.env.CORS_ALLOWED ?? 'true') !== 'false',
      actions: {
        'init-session': 'InitSessionController',
        // ……每个动作一个条目(参见 actions-registry.service.ts),
        // 仅为文档目的而保留
      },
      types: ['json', 'html', 'xml'],
      users: [{ login: 'admin', passwd: 'admin' }],
      taxDataSource: (process.env.TAX_DATA_SOURCE as 'json' | 'mysql') ?? 'json',
      jsonTaxDataFile: path.join(process.cwd(), 'data', 'tax-admin-data.json'),
      mysql: {
        host: process.env.DB_HOST ?? 'localhost',
        port: Number(process.env.DB_PORT ?? 3306),
        database: process.env.DB_NAME ?? 'dbtaxes-2019',
        user: process.env.DB_USER ?? 'admtaxes',
        password: process.env.DB_PASSWORD ?? 'pwdtaxes',
      },
      logsFilename: path.join(process.cwd(), 'Logs', 'logs.txt'),
      sessionSecret: process.env.SESSION_SECRET ?? 'change-me-in-production',
      views: {
        'view-authentication': [700, 221, 400],
        'view-tax-calculation': [200, 300, 341, 350, 800],
        'view-simulations-list': [500, 600],
      },
      errorsView: 'view-errors',
      viewsDir: path.join(process.cwd(), 'views'),
    };
    const logsDir = path.dirname(this.config.logsFilename);
    if (!fs.existsSync(logsDir)) {
      fs.mkdirSync(logsDir, { recursive: true });
    }
  }
}

我们来解读这段代码:

  • actions: { ... } —— 保留此表纯粹是为了文档目的(它准确地描述了原始架构):动作的实际路由并不依赖它,而是通过 ActionsRegistryService 中的依赖注入来处理;
  • taxDataSource: (process.env.TAX_DATA_SOURCE as ...) ?? 'json' —— 读取自环境变量 TAX_DATA_SOURCE,该字段选择 ServerDaoService 所使用的税务数据源(见上文);
  • views: { ... } —— 将每个 EJS 模板名称与应显示它的响应状态列表关联起来(例如,view-tax-calculation 对应状态 200, 300、341、350、800);HtmlViewRendererService (见“构建 HTML 页面”)使用此表来选择要渲染的视图;
  • errorsView: 'view-errors' —— 回退视图,当没有任何 views 条目与当前状态匹配时显示;
  • 最后一行:if (!fs.existsSync(logsDir)) { fs.mkdirSync(logsDir, { recursive: true }); } —— 创建时,该服务自身会在 Logs/ 文件夹尚不存在时创建它,这样 LoggerService 就可以随时向其中写入,而无需为此操心。

9.10. 实体、会话和日志

src/entities/ 包含三个数据类,移植自 Entities/*.php。摘自 simulation.entity.ts——一次税额计算模拟,存储在 session.simulations 中:

export class Simulation {
  married: string;
  children: number;
  salary: number;
  tax: number;
  surcharge: number;
  discount: number;
  reduction: number;
  rate: number;

  static fromAttributes(attributes: Partial<Simulation>): Simulation {
    const simulation = new Simulation();
    Object.assign(simulation, attributes);
    return simulation;
  }
}

摘自 tax-admin-data.entity.ts——由 [DAO] 层读取的税率档次和计算常量:

export class TaxAdminData {
  limits: number[] = [];
  coeffR: number[] = [];
  coeffN: number[] = [];
  halfShareQfCeiling = 0;
  // ……其余八个计算常量(参见源文件)

  static fromAttributes(attributes: Partial<TaxAdminData>): TaxAdminData {
    const entity = new TaxAdminData();
    Object.assign(entity, attributes);
    return entity;
  }
}

以及 tax-exception.ts —— 一个带类型的应用异常,当数据源不可访问(jSON 文件不可读、MySQL 连接失败……)时由 [DAO] 层抛出,并由需要它的动作处理器(calculate-tax、 get-admindata)拦截:

1
2
3
4
5
6
export class TaxException extends Error {
  constructor(message: string, public readonly code: number = 0) {
    super(message);
    this.name = 'TaxException';
  }
}

src/session/session.types.ts 不是服务:它是一个类型声明,用于扩展 express-session 模块,使 TypeScript 能够访问应用特有的内容(会话类型、已认证用户、已保存的模拟):

1
2
3
4
5
6
7
8
9
declare module 'express-session' {
  interface SessionData {
    type?: 'json' | 'html' | 'xml';
    user?: boolean;
    simulations?: Simulation[];
  }
}

export type AppSession = Session & Partial<SessionData>;
注意:这项技术——模块扩展(`declare module 'express-session'`)——使得你可以在项目的其他地方编写 `request.session.simulations` 或 `session.user` ,而不会让 `TypeScript` 编译器报错;AppSession,即所有动作控制器中使用的 req.session 的实际类型,就是直接由此派生而来。

最后,src/utilities/logger.service.ts 会把服务器所做的一切(新请求、请求的动作、选中的控制器、返回的响应等)记录到 Logs/logs.txt 中:

@Injectable()
export class LoggerService {
  constructor(private readonly configService: ConfigService) {}

  write(message: string): void {
    const timestamp = new Date().toISOString().replace('T', ' ').replace('Z', '');
    fs.appendFile(
      this.configService.config.logsFilename,
      `${timestamp} : ${message}\n`,
      () => { /* 尽力而为的日志写入,与 PHP 端一样 */ },
    );
  }
}
注意:写入以尽力而为的模式执行(异步的 fs.appendFile,不等待也不验证结果):写日志时出现问题绝不应导致请求失败——这正是 PHP 端 Utilities/Logger.php 所采取的做法。

9.11. jSON、XML 和 HTML 响应

ResponseSenderService 构造 jSON 或 XML 响应(使用 js2xmlparser 库),复刻原 PHP 服务器对 CORS 的处理(Access-Control-Allow-* 头仅针对 localhost 来源),并处理 OPTIONS 方法(CORS 预检)的特殊情况。

摘自 src/responses/response-sender.service.ts,它实际构造这个响应:

async send(
  request: Request, response: Response, config: AppConfig,
  statusCode: number, content: Record<string, unknown>,
  headers: Record<string, string>, type: 'json' | 'html' | 'xml',
): Promise<void> {
  let body: string;
  let contentType: string;
  switch (type) {
    case 'xml':
      body = js2xmlparser.parse('root', content);
      contentType = 'application/xml';
      break;
    case 'html':
      body = await this.htmlViewRenderer.render(content, request);
      contentType = 'text/html';
      break;
    case 'json':
    default:
      body = JSON.stringify(content);
      contentType = 'application/json';
      break;
  }
  headers = { ...headers, 'content-type': contentType };
  this.sendResponse(request, response, statusCode, body, headers, config);
  this.logger.write(`response=${JSON.stringify(content)}\n`);
}

private sendResponse(
  request: Request, response: Response, statusCode: number,
  content: string, headers: Record<string, string>, config: AppConfig,
): void {
  if (config.corsAllowed) {
    const origin = request.headers.origin ?? '';
    if (origin.startsWith('http://localhost') || origin.startsWith('https://localhost')) {
      headers = {
        ...headers,
        'Access-Control-Allow-Origin': origin,
        'Access-Control-Allow-Headers': 'Accept, Content-Type',
        'Access-Control-Allow-Methods': 'GET, POST',
        'Access-Control-Allow-Credentials': 'true',
      };
    }
  }
  const method = request.method.toLowerCase();
  if (method === 'options') {
    content = '';
    statusCode = 200;
  }
  Object.entries(headers).forEach(([name, value]) => response.setHeader(name, value));
  response.status(statusCode).send(content);
}

我们来解读这段代码:

  • switch (type) { ... } —— 三种响应格式在这里构造,而且只在这里构造:JSON 通过 JSON.stringify,XML 通过 js2xmlparser 库(它把 content 对象转换为 XML 文档,以 <root> 元素作为根),以及 HTML 则完全委托给 HtmlViewRendererService.render(...),详见下文;
  • this.logger.write(response=${JSON.stringify(content)}); —— 即使在 HTML 模式下,记录的也是响应的应用内容 (content),而绝不是生成的整个 HTML 页面——与 HtmlResponse.php 的做法一样;
  • 在 sendResponse(...) 中,检查 origin.startsWith('http://localhost') || origin.startsWith('https://localhost') 完全复刻了原 PHP 服务器的 CORS 策略(ParentResponse::sendResponse):只有 localhost 来源才会收到 Access-Control-Allow-* 头;绝不会给任意域名;
  • if (method === 'options') { content = ''; statusCode = 200; } —— CORS 预检的特殊情况:对于 OPTIONS 请求,只有响应头重要;响应体会被清空,状态码会被强制设为 200,无论所请求的处理是什么。

对于 type=html 模式,HtmlViewRendererService 复刻了 PHP 服务器的视图选择逻辑:每个响应状态对应一个视图,从配置表中选取,如果没有视图匹配,则回退到通用错误页面。每个视图都是一个 EJS 模板(views/*.ejs),是对原 PHP 文件的直接翻译,由专用函数生成的“显示模板”驱动——与 getModelForThisView(...) / PHP 视图这一对的原理相同,并额外带来对显示值的自动转义。

注意:对于在别处接触过 NestJS 的读者:此 HTML 渲染没有使用 NestJS 提供的 @Render() 装饰器来把控制器方法与视图引擎(EJS、Handlebars、Pug……)关联起来 -- 该机制要求传统的 NestJS 控制器每个视图对应一个路由,这与此服务器的单一前端控制器不兼容。因此 ejs.renderFile(...) 是在 HtmlViewRendererService 中直接手动调用的,然后生成的 HTML 通过 @Res() (见上文)以纯文本形式发送:这是使用 NestJS 渲染视图的一种完全有效的替代方案,只是不经过这个特定的装饰器。

9.12. 构建 HTML 页面

我们来仔细看看 type=html 模式,其机制分解在三个不同的文件中:视图的选择与渲染(src/views/html-view-renderer.service.ts)、每个视图专属的“显示模板”的构造(src/views/view-models.ts),以及模板本身(views/*.ejs 和 views/partials/*.ejs,位于项目根目录——不要与 src/views/ 文件夹混淆,后者只包含 TypeScript)。

摘自 src/views/html-view-renderer.service.ts:

@Injectable()
export class HtmlViewRendererService {
  constructor(private readonly configService: ConfigService) {}

  async render(content: Record<string, unknown>, request: Request): Promise<string> {
    const { views, errorsView, viewsDir } = this.configService.config;
    const status = content['status'] as number;

    const viewName = Object.keys(views).find((view) => views[view].includes(status)) ?? errorsView;

    const logo = buildLogoPath(request);

    let model: unknown;
    switch (viewName) {
      case 'view-authentication':
        model = buildAuthenticationModel(status, request);
        break;
      case 'view-tax-calculation':
        model = buildTaxCalculationModel(status, request, content);
        break;
      case 'view-simulations-list':
        model = buildSimulationsListModel(content);
        break;
      case 'view-errors':
      default:
        model = buildErrorsModel(content);
        break;
    }

    const templateFile = path.join(viewsDir, `${viewName}.ejs`);
    return ejs.renderFile(templateFile, { model, logo }, { views: [viewsDir, path.join(viewsDir, 'partials')] });
  }
}

我们来解读这段代码:

  • const viewName = Object.keys(views).find((view) => views[view].includes(status)) ?? errorsView; —— 整个机制的关键一行:我们在 config.views 表(见上文)中查找其状态列表包含当前响应状态的视图名称;如果没有任何匹配项——包括README 中指出的情况,即没有专用视图的 成功 状态,例如 get-admindata/1000——则回退到 errorsView(view-errors),其逻辑与 PHP 端的 HtmlResponse::send() 完全相同;
  • const logo = buildLogoPath(request); —— 每个请求都会根据所请求的 URL 重新计算 logo 路径(见下文的 view-models.ts ),以确保即使应用部署在子目录中该路径依然正确;
  • switch (viewName) { case 'view-authentication': model = buildAuthenticationModel(...); ... } —— 选定视图后,会调用相应的模型构建函数(详见下文);EJS 模板将显示的正是这个模型,也仅仅是这个模型;
  • return ejs.renderFile(templateFile, { model, logo }, { views: [viewsDir, path.join(viewsDir, 'partials')] }); —— 对 EJS 的实际调用:ejs.renderFile(...) 读取相应的 .ejs 文件,在 model 和 logo 变量的上下文中执行它,并以字符串形式返回生成的 HTML——views 选项告诉 EJS 在哪两个目录中查找按名称包含的模板(views 文件夹及其 partials/ 子文件夹)。

src/views/view-models.ts 为每个视图定义了一个模型构建函数——相当于原 PHP 各视图中都有的函数 getModelForThisView(...) 的 TypeScript 版本(Views/view-*.php)。下面是四个函数中最简单的 buildAuthenticationModel 的节选:

export function buildAuthenticationModel(
  status: number,
  request: Request,
): AuthenticationModel {
  const model: AuthenticationModel = { login: '', error: false, errors: [] };
  switch (status) {
    case 700:
    case 400:
      model.login = '';
      model.error = false;
      break;
    case 221:
      model.login = String(request.body?.user ?? '');
      model.error = true;
      model.errors = ["Authentication failed"];
      break;
  }
  return model;
}

以及最复杂的 buildTaxCalculationModel,它必须处理三种不同的情况:

export function buildTaxCalculationModel(
  status: number,
  request: Request,
  content: Record<string, unknown>,
): TaxCalculationModel {
  const model: TaxCalculationModel = {
    success: false, error: false, checkedYes: false, checkedNo: false,
    children: '', salary: '', errors: [],
    optionsMenu: {
      'List of simulations': 'main.php?action=list-simulations',
      'End of session': 'main.php?action=end-session',
    },
  };
  switch (status) {
    case 200:
    case 800:
      model.success = false;
      model.error = false;
      model.checkedNo = true;
      model.checkedYes = false;
      model.children = '';
      model.salary = '';
      break;
    case 300: {
      const response = content.response as Record<string, unknown>;
      model.success = true;
      model.error = false;
      model.tax = `Tax amount: ${response.tax} euros`;
      model.discount = `Discount: ${response.discount} euros`;
      model.reduction = `Reduction: ${response.reduction} euros`;
      model.surcharge = `Surcharge: ${response.surcharge} euros`;
      model.rate = `Tax rate: ${(response.rate as number) * 100} %`;
      const married = request.body?.['married'];
      model.checkedYes = married === 'yes';
      model.checkedNo = married !== 'yes';
      model.children = String(request.body?.children ?? '');
      model.salary = String(request.body?.salary ?? '');
      break;
    }
    case 341:
    case 350: {
      const married = request.body?.['married'];
      model.checkedYes = married === 'yes';
      model.checkedNo = married !== 'yes';
      model.children = String(request.body?.children ?? '');
      model.salary = String(request.body?.salary ?? '');
      model.success = false;
      model.error = true;
      model.errors = [String(content.response)];
      break;
    }
  }
  return model;
}

我们来解读这段代码:

  • 状态码 200 和 800 (空表单、进入该视图,或从 display-tax-calculation 返回)——模型中的所有字段都被重置为空,就好像表单从未被填写过;
  • 状态 300 (计算成功)—— const response = content.response as Record<string, unknown>; 获取 CalculateTaxController 返回的结果(税额、折扣、减免、附加税、税率),并构造成功横幅中显示的五个句子;表单会重新填入提交的值(request.body),以便用户在查看结果的同时核对自己的输入;
  • 状态 341 和 350 (数据库或 Redis 宕机)——同样重新显示已提交的表单,但会设置 model.error = true ,并将 [DAO] 层返回的错误消息放入 model.errors;
  • optionsMenu: { ... } —— 侧边菜单(属于 menu.ejs,见下文)与状态无关:无论计算结果如何,它始终存在,并且始终是相同的两个选项。

其余两个函数遵循相同的原则:

  • buildSimulationsListModel(content) —— 四个函数中最短的一个:simulations: (content.response as SimulationRow[]) ?? [],再加上与 buildTaxCalculationModel 相同的侧边菜单(这次包含“税额计算”和“结束会话”);
  • buildErrorsModel(content) —— 构建通用 "view-errors" 视图所显示的消息列表;它处理一种继承自原 PHP 的非常特殊的情况:else if (response !== null && typeof response === 'object') { errors = [JSON.stringify(response)]; },即当一个没有专用视图的 成功 状态(例如 get-admindata/1000)仍然回退到该错误视图时——原 PHP 此时会通过其 __toString() 方法显示该对象;JSON.stringify 是 TypeScript 中的等价做法。
  • buildLogoPath(request) —— const root = pathname.replace(/\/[^/]*$/, ''); return ${root}/Resources/logo.jpg; :根据当前 URL 的目录(不含脚本名)重建 logo 路径,使得即使应用部署在子目录中,横幅依然正确——直接移植自 Views/v-banner.php。

四个 views/*.ejs 模板是原 PHP 文件(Views/view-*.php)的直接翻译,采用相同的 Bootstrap 4.1.3 布局。最完整的节选是 view-tax-calculation.ejs:

<%# equivalent of Views/view-tax-calculation.php %>
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" ...>
    <title>Tax application</title>
  </head>
  <body>
    <div class="container">
      <%- include('partials/banner', { logo: logo }) %>
      <div class="row">
        <div class="col-md-3">
          <%- include('partials/menu', { model: model }) %>
        </div>
        <div class="col-md-9">
          <%- include('partials/tax-calculation-form', { model: model }) %>
        </div>
      </div>
      <% if (model.success) { %>
      <div class="row">
        <div class="col-md-9">
          <div class="alert alert-success" role="alert">
            <%= model.tax %><br>
            <%= model.discount %><br>
            ...
          </div>
        </div>
      </div>
      <% } %>
      <% if (model.error) { %>
        ... (same principle, alert-danger, loop over model.errors)
      <% } %>
    </div>
  </body>
</html>

我们来解读这个模板:

  • 第 1 行:<%# ... %> —— EJS 注释,永远不会发送到浏览器;
  • <%- include('partials/banner', { logo: logo }) %> —— 包含一个局部模板,并附带我们希望显式传递给它的变量(这里是 logo);注意:<%- %> 显示结果时不进行转义——在这里仅用于插入已由 include(...) 构造好的 HTML,绝不用于用户输入的数据;
  • <% if (model.success) { %> ... <% } %> —— EJS 控制块(<% %>,不带连字符):在渲染期间执行的 JavaScript,本身不产生任何输出;在这里,只有当 model.success 为 true 时,“结果”部分才会出现在最终的 HTML 中;
  • <%= model.tax %> —— 转义显示(<%= %>,带等号):这是用于任何可能包含用户输入的数据(计算结果、重新显示的登录名、错误消息)的形式——EJS 会自动转义特殊字符,而原 PHP 中的 <?= ?> 则不会。

其余三个视图和五个局部模板(views/partials/)遵循相同的原则:

  • view-authentication.ejs —— 登录表单;包含 partials/banner 和 partials/authentication-form,然后显示列表 model.errors if model.error;
  • view-simulations-list.ejs —— 包含 partials/banner、partials/menu、以及 partials/simulations-list-table;
  • view-errors.ejs —— 回退视图:partials/banner、partials/menu,后面是一个简单的循环 <% model.errors.forEach(function(error) { %><li><%= error %></li><% }) %>;
  • partials/banner.ejs —— logo 和 “计算您的税额” 标题,除 身份验证视图外所有视图共用,身份验证视图同样包含它们;
  • partials/menu.ejs —— <% Object.keys(model.optionsMenu).forEach(function(text) { %><a href="<%= model.optionsMenu[text] %>"><%= text %></a><% }) %>:侧边菜单,完全由 optionsMenu 表控制,该表在 view-models.ts 中创建——因此添加菜单选项只需修改模型,无需改动此模板;
  • partials/authentication-form.ejs —— Bootstrap 登录表单,使用 value="<%= model.login %>" 在登录失败时重新显示上次输入的登录名;
  • partials/tax-calculation-form.ejs —— 计算表单;请注意 <%- model.checkedYes ? 'checked="checked"' : '' %>:这是对 有意为之且安全地使用 <%- %>,因为插入的字符串(checked="checked" 或空字符串)是在服务器端设置的,绝不会由用户输入构造而成;
  • partials/simulations-list-table.ejs —— 模拟表格,model.simulations 中的每一项对应一行,每行带有一个 “删除” 链接,指向 main.php?action=delete-simulation&number=... 。
注意:与原 PHP 不同,原 PHP 通过 <?= ?> 在不转义的情况下重新注入某些值(这是一个 XSS 反射型漏洞,尤其可通过身份验证表单被利用),而本项目中的 EJS 模板对所有用户提供的数据(登录名、子女数、薪资、错误消息)一律使用 <%= %> 。本项目中少数几处使用 <%- %> 的地方,仅用于包含局部模板,或插入由固定值在服务器端构造的属性——绝不涉及用户输入:这种行为在功能上与 PHP 服务器完全相同,却不会重蹈其漏洞。

9.13. 执行

在 [nestjs-case-study] 文件夹的根目录下:

npm install
cp .env.example .env
npm run start:dev

服务器随后监听 http://localhost:3000。TypeScript 客户端使用的 jSON 模式,可通过以下方式测试:

http://localhost:3000/main.php?action=init-session&type=json

而 HTML 模式则直接在浏览器中,通过以下方式测试:

http://localhost:3000/main.php?action=init-session&type=html

在这两种情况下,同一个 action 参数决定所执行的处理(此处为 init-session,它必须是第一个被调用的操作,因为它会初始化会话),而 type 参数决定响应格式——其他操作也以同样的方式进行测试,只需更改 action 的值(例如 &action=calculate-tax,使用 POST,并提交参数 “married”、“children”和 “salary”)。

打开浏览器并请求 URL [http://localhost:3000/main.php?action=init-session&type=html]

Image

登录凭据为 admin / admin。提交表单。

Image

填写表单后提交:

Image

运行若干次模拟,然后请求 [List of simulations]:

Image

删除这两个模拟:

Image

结束会话:

Image