Skip to content

9. 分层架构与数据访问

前面的示例都把数据保存在内存中。真正的应用会把数据存储在数据库中,并按 层 组织(参见引言中的图):

  • Web 层(控制器、视图):读取请求,调用业务层,选择视图;
  • 业务层:业务规则;
  • DAO 层:数据库查询。

每一层只了解它下面的一层,而且了解的细节尽可能少:Web 层不了解 SQL 层,业务层不了解 HTML 层。这种分离使每一层都更容易理解、测试和演进。示例 28 把这一点应用于一个人员列表的管理:这是案例研究中医生和客户管理的缩小版。

9.1. 示例 28:用于管理人员的三层系统

28-layers/
├── database/
│   └── dbpersons.sql
├── public/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── src/
│   ├── business/
│   │   ├── business.exception.ts
│   │   └── persons.business.ts
│   ├── config/
│   │   └── database.config.ts
│   ├── dao/
│   │   └── persons.dao.ts
│   ├── entities/
│   │   └── person.entity.ts
│   ├── web/
│   │   ├── flash.ts
│   │   ├── person-form.dto.ts
│   │   ├── persons.controller.ts
│   │   └── validation.ts
│   ├── app.module.ts
│   └── main.ts
├── views/
│   ├── partials/
│   │   └── confirmation.hbs
│   ├── form.hbs
│   ├── layout.hbs
│   └── list.hbs
├── nest-cli.json
└── tsconfig.json

9.1.1. 数据库

数据库 [dbpersons] 由一个 SQL 脚本创建。使用 [Laragon] 时,可以在 [HeidiSQL] 工具中运行它(文件菜单 / 运行 SQL 文件),或者在命令行中运行:

mysql -u root < database/dbpersons.sql

[database/dbpersons.sql] 文件:

-- database of example 28: a single table, [persons]
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbpersons;

CREATE TABLE persons (
  id INT NOT NULL AUTO_INCREMENT,
  version INT NOT NULL DEFAULT 1,
  first_name VARCHAR(30) NOT NULL,
  last_name VARCHAR(30) NOT NULL,
  age INT NOT NULL,
  PRIMARY KEY (id),
  -- two persons cannot have the same first and last names
  CONSTRAINT unq_persons_first_name_last_name UNIQUE (first_name, last_name)
) ENGINE = InnoDB;

INSERT INTO persons (first_name, last_name, age) VALUES
  ('Marie', 'Pélissier', 42),
  ('Jacques', 'Bromard', 35),
  ('Philippe', 'Jandot', 58);
  • 第 3 行:[utf8mb4] 字符集接受所有字符(重音符号、表情符号等)。排序规则 [utf8mb4_unicode_ci] 比较字符串时 不区分大小写和重音:对 MySQL 来说,[pelissier]、与 [Pélissier] 是相等的;
  • 第 8 行:版本号,每次修改该行时递增(参见下面的“乐观锁”);
  • 第 14 行:一个命名的 唯一性约束:数据库不允许两个人具有相同的名和姓。该名称将用于识别错误。

9.1.2. TypeORM 的配置

[src/config/database.config.ts] 文件:

import { TypeOrmModuleOptions } from '@nestjs/typeorm';
import { Person } from '../entities/person.entity';

// 数据库连接;默认值是 Laragon 的默认值
export function databaseConfig(): TypeOrmModuleOptions {
  return {
    type: 'mysql',
    host: process.env.DB_HOST ?? 'localhost',
    port: Number(process.env.DB_PORT ?? 3306),
    username: process.env.DB_USERNAME ?? 'root',
    password: process.env.DB_PASSWORD ?? '',
    database: 'dbpersons',
    entities: [Person],
    // 数据库结构由 SQL 脚本创建,TypeORM 绝不修改
    synchronize: false,
    // DB_LOGGING=true:显示发送到数据库的 SQL 语句
    logging: process.env.DB_LOGGING === 'true',
  };
}
  • 第 8–11 行:连接参数,从环境变量中读取,默认值来自 [Laragon] (用户名 [root],没有密码);
  • 第 13 行:[TypeORM] 映射到表的类;
  • 第 15 行:[TypeORM] 可以根据类自行创建或修改表。这对原型来说很方便,但对于已有数据的数据库则很危险:模式仍由 SQL 脚本负责;
  • 第 17 行:使用环境变量 [DB_LOGGING=true] 时,发送到数据库的 SQL 命令会显示在控制台中。

9.1.3. Person 实体

文件 [src/entities/person.entity.ts]:

import { Column, Entity, PrimaryGeneratedColumn, VersionColumn } from 'typeorm';

// [persons] 表的一行 <-> 一个 Person 对象
@Entity('persons')
export class Person {
  @PrimaryGeneratedColumn()
  id: number;

  // 每次修改时由 TypeORM 递增(乐观锁)
  @VersionColumn()
  version: number;

  @Column({ name: 'first_name', length: 30 })
  firstName: string;

  @Column({ name: 'last_name', length: 30 })
  lastName: string;

  @Column()
  age: number;
}
  • 第 4 行:类 [Person] 对应于表 [persons]:该表的每一行都将是一个 [Person] 对象;
  • 第 6 行:主键,由数据库生成([AUTO_INCREMENT]);
  • 第 10 行:版本列,由 [TypeORM] 管理;
  • 第 13–20 行:其他列。

9.1.4. DAO 层

文件 [src/dao/persons.dao.ts]:

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Not, Repository } from 'typeorm';
import { Person } from '../entities/person.entity';

// 数据访问层:查询,不含业务规则
@Injectable()
export class PersonsDao {
  constructor(@InjectRepository(Person) private readonly repository: Repository<Person>) {}

  // 在事务内部,必须通过事务的 "manager"
  private repo(manager?: EntityManager): Repository<Person> {
    return manager ? manager.getRepository(Person) : this.repository;
  }

  list(): Promise<Person[]> {
    return this.repository.find({ order: { lastName: 'ASC', firstName: 'ASC' } });
  }

  read(id: number, manager?: EntityManager): Promise<Person | null> {
    return this.repo(manager).findOneBy({ id });
  }

  // 另一个人(id 不同于 [exceptId]),具有这些姓和名
  namesake(firstName: string, lastName: string, exceptId: number, manager?: EntityManager): Promise<Person | null> {
    return this.repo(manager).findOneBy({ firstName, lastName, id: Not(exceptId) });
  }

  // 如果该人没有 id 则 INSERT,否则 UPDATE
  save(person: Person, manager?: EntityManager): Promise<Person> {
    return this.repo(manager).save(person);
  }

  async delete(id: number, manager?: EntityManager): Promise<void> {
    await this.repo(manager).delete(id);
  }
}
  • 第 9 行:[TypeORM] 为每个实体提供一个 仓库 ([Repository<Person>]),它可以读写对应的表。[@InjectRepository] 负责注入它;
  • 第 12–14 行:在 事务中,所有查询都必须通过同一个 [EntityManager] 对象——与该事务关联的那个。因此每个方法都接受一个可选的 [manager];
  • 第 16–18 行:带排序的 [find] :[SELECT ... ORDER BY last_name, first_name];
  • 第 25–27 行:具有相同名和姓的人员,但不是 [exceptId] ([Not]):这对修改记录很有用,因为记录不能与自身冲突;
  • 第 30–32 行:如果对象没有标识符,[save] 会变成 [INSERT] ,否则变成 [UPDATE] 。

DAO 层不包含任何规则:只有查询。

9.1.5. 业务层

文件 [src/business/business.exception.ts]:

1
2
3
// 业务规则拒绝了该操作:这不是异常情况,
// 消息是给用户看的
export class BusinessException extends Error {}

[BusinessException] 表示某条业务规则拒绝了一个操作。这不是程序错误:消息是给用户看的。

[src/business/persons.business.ts] 文件:

import { Injectable } from '@nestjs/common';
import { DataSource, EntityManager } from 'typeorm';
import { PersonsDao } from '../dao/persons.dao';
import { Person } from '../entities/person.entity';
import { BusinessException } from './business.exception';

export interface PersonData {
  firstName: string;
  lastName: string;
  age: number;
}

// 业务层:业务规则,且仅限业务规则
@Injectable()
export class PersonsBusiness {
  constructor(
    private readonly dao: PersonsDao,
    private readonly dataSource: DataSource,
  ) {}

  list(): Promise<Person[]> {
    return this.dao.list();
  }

  async read(id: number): Promise<Person> {
    const person = await this.dao.read(id);
    if (!person) {
      throw new BusinessException('This person does not exist (anymore).');
    }
    return person;
  }

  add(data: PersonData): Promise<Person> {
    return this.transaction(async (manager) => {
      // 规则 1:不允许有两个姓和名相同的人
      if (await this.dao.namesake(data.firstName, data.lastName, 0, manager)) {
        throw new BusinessException('A person already has these first and last names.');
      }
      const person = new Person();
      person.firstName = data.firstName;
      person.lastName = data.lastName;
      person.age = data.age;
      return this.dao.save(person, manager);
    });
  }

  edit(id: number, version: number, data: PersonData): Promise<Person> {
    return this.transaction(async (manager) => {
      const person = await this.dao.read(id, manager);
      if (!person) {
        throw new BusinessException('This person does not exist (anymore).');
      }
      // 规则 2:不修改在此期间已被他人修改的记录
      if (person.version !== version) {
        throw new BusinessException('This record has been modified meanwhile: reload it.');
      }
      if (await this.dao.namesake(data.firstName, data.lastName, id, manager)) {
        throw new BusinessException('A person already has these first and last names.');
      }
      person.firstName = data.firstName;
      person.lastName = data.lastName;
      person.age = data.age;
      return this.dao.save(person, manager);
    });
  }

  async delete(id: number): Promise<Person> {
    const person = await this.read(id);
    await this.dao.delete(id);
    return person;
  }

  // [work] 在事务内运行:成功则 COMMIT,抛出异常则 ROLLBACK。
  // 违反唯一性约束(例如两次
  // 同时添加)会变成 BusinessException
  private async transaction<R>(work: (manager: EntityManager) => Promise<R>): Promise<R> {
    try {
      return await this.dataSource.transaction(work);
    } catch (e) {
      const sqlError = e as { code?: string; message?: string };
      if (sqlError.code === 'ER_DUP_ENTRY' && sqlError.message?.includes('unq_persons_first_name_last_name')) {
        throw new BusinessException('A person already has these first and last names.');
      }
      throw e;
    }
  }
}

我们来逐行剖析这段代码:

  • 第 16–19 行:业务层使用 DAO,以及来自 [DataSource] 的 [TypeORM] (数据库连接)来开启事务;
  • 第 25–31 行:不存在的人员会抛出 [BusinessException];
  • 第 33–45 行:在事务中添加一个人员。规则:不允许有两个人具有相同的名和姓。这一检查在写操作 之前进行,以便显示清晰的消息;
  • 第 47–65 行:修改。附加规则:乐观锁 (第 54–56 行):修改表单携带的是打开表单时该记录的版本。如果在此期间它已经改变(另一个用户修改了同一条记录),该操作就会被拒绝,而不是悄悄地覆盖用户的工作;
  • 第 76–86 行:[dataSource.transaction(work)] 开启一个事务,执行 [work],然后提交它([COMMIT]),或者在 [work] 抛出异常时回滚它([ROLLBACK])。第 81–82 行:事先检查同名人员并不总是足够:两个用户可能同时添加同一个人,而且两者都可能通过检查。然而,数据库的唯一性约束不允许任何例外;此时由约束标识的 MySQL 错误 [ER_DUP_ENTRY] 会变成同样的 [BusinessException]。

9.1.6. Web 层

文件 [src/web/person-form.dto.ts]:

import { Transform, Type } from 'class-transformer';
import { IsInt, IsNotEmpty, Max, MaxLength, Min } from 'class-validator';

const clean = ({ value }: { value: unknown }) => (typeof value === 'string' ? value.trim() : value);

// 表单的字段及其约束(长度 = SQL 列的长度)
export class PersonFormDto {
  @Transform(clean)
  @IsNotEmpty({ message: 'The first name is required.' })
  @MaxLength(30, { message: 'The first name must not exceed 30 characters.' })
  firstName: string;

  @Transform(clean)
  @IsNotEmpty({ message: 'The last name is required.' })
  @MaxLength(30, { message: 'The last name must not exceed 30 characters.' })
  lastName: string;

  @Type(() => Number)
  @IsInt({ message: 'The age must be an integer.' })
  @Min(0, { message: 'The age must be positive.' })
  @Max(150, { message: 'The age cannot exceed 150.' })
  age: number;
}

表单及其约束(参见示例 19)。函数 [validateForm] (文件 [web/validation.ts])与示例 19 中的相同,而 [web/flash.ts] 与示例 20 中的相同,只是增加了消息类型(成功或错误)。

文件 [src/web/persons.controller.ts]:

import { Body, Controller, Get, Param, ParseIntPipe, Post, Redirect, Render, Res } from '@nestjs/common';
import { Response } from 'express';
import { BusinessException } from '../business/business.exception';
import { PersonsBusiness } from '../business/persons.business';
import { flash } from './flash';
import { PersonFormDto } from './person-form.dto';
import { validateForm } from './validation';

// Web 层:读取请求,调用业务层,选择视图
@Controller()
export class PersonsController {
  constructor(private readonly business: PersonsBusiness) {}

  @Get()
  @Redirect('/persons')
  root(): void {}

  @Get('persons')
  @Render('list')
  async list(): Promise<object> {
    return { persons: await this.business.list() };
  }

  @Get('persons/add')
  @Render('form')
  addForm(): object {
    return { title: 'Add a person', action: '/persons/add', values: {}, errors: {} };
  }

  @Post('persons/add')
  async add(@Body() body: Record<string, string>, @Res() res: Response): Promise<void> {
    const view = { title: 'Add a person', action: '/persons/add' };
    const { dto, errors } = await validateForm(PersonFormDto, body);
    if (Object.keys(errors).length > 0) {
      res.render('form', { ...view, values: body, errors, error: 'The form contains errors.' });
      return;
    }
    try {
      const p = await this.business.add(dto);
      flash(res, { type: 'success', text: `${p.firstName} ${p.lastName} has been added.` });
      res.redirect('/persons');
    } catch (e) {
      // 业务规则拒绝了添加:再次显示表单
      if (!(e instanceof BusinessException)) throw e;
      res.render('form', { ...view, values: body, errors: {}, error: e.message });
    }
  }

  @Get('persons/:id/edit')
  @Render('form')
  async editForm(@Param('id', ParseIntPipe) id: number): Promise<object> {
    const p = await this.business.read(id);
    return { title: 'Edit a person', action: `/persons/${id}/edit`, values: p, errors: {} };
  }

  @Post('persons/:id/edit')
  async edit(
    @Param('id', ParseIntPipe) id: number,
    @Body() body: Record<string, string>,
    @Res() res: Response,
  ): Promise<void> {
    const view = { title: 'Edit a person', action: `/persons/${id}/edit` };
    const { dto, errors } = await validateForm(PersonFormDto, body);
    if (Object.keys(errors).length > 0) {
      res.render('form', { ...view, values: body, errors, error: 'The form contains errors.' });
      return;
    }
    try {
      const p = await this.business.edit(id, Number(body.version), dto);
      flash(res, { type: 'success', text: `${p.firstName} ${p.lastName} has been modified.` });
      res.redirect('/persons');
    } catch (e) {
      if (!(e instanceof BusinessException)) throw e;
      res.render('form', { ...view, values: body, errors: {}, error: e.message });
    }
  }

  @Post('persons/:id/delete')
  async delete(@Param('id', ParseIntPipe) id: number, @Res() res: Response): Promise<void> {
    try {
      const p = await this.business.delete(id);
      flash(res, { type: 'success', text: `${p.firstName} ${p.lastName} has been deleted.` });
    } catch (e) {
      if (!(e instanceof BusinessException)) throw e;
      // 没有表单可再次显示:错误同样以 flash 的方式传递
      flash(res, { type: 'danger', text: e.message });
    }
    res.redirect('/persons');
  }
}

我们来逐行说明这段代码:

  • 第 12 行:控制器只了解业务层;
  • 第 14–16 行:站点根路径重定向到列表;
  • 第 18–22 行:一个异步操作:从数据库获取列表;
  • 第 30–47 行:添加操作,分三步:表单验证(有错误 → 重新加载页面)、调用业务层(成功 → 闪现消息并重定向)、[BusinessException] (→ 重新加载页面,消息显示在页面底部)。如果抛出其他异常([throw e]):这是一种异常情况,[NestJS] 的异常过滤器会把它转换为 500 错误;
  • 第 49–54 行:更新表单,用从数据库获取的记录(包括其版本)预先填充;
  • 第 56–61 行:与添加记录相同的流程;表单返回的版本会传给业务层;
  • 第 78–89 行:删除。没有需要重新显示的表单:任何错误也包含在闪现消息中。

文件 [src/app.module.ts]:

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { databaseConfig } from './config/database.config';
import { PersonsDao } from './dao/persons.dao';
import { Person } from './entities/person.entity';
import { PersonsBusiness } from './business/persons.business';
import { PersonsController } from './web/persons.controller';

@Module({
  imports: [
    // 整个应用程序的数据库连接
    TypeOrmModule.forRoot(databaseConfig()),
    // 可在此模块中注入的 Repository<T>
    TypeOrmModule.forFeature([Person]),
  ],
  controllers: [PersonsController],
  // 三层:web(控制器)-> 业务层 -> dao
  providers: [PersonsBusiness, PersonsDao],
})
export class AppModule {}
  • 第 12 行:整个应用的数据库连接;
  • 第 14 行:使 [Repository<Person>] 能够被注入;
  • 第 18 行:业务层服务和 DAO。

[views/form.hbs] 文件:

<h1 class="h3">{{title}}</h1>
<form method="post" action="{{action}}" novalidate>
  {{!-- 所读取记录的版本,随修改请求一并回传 --}}
  <input type="hidden" name="version" value="{{values.version}}">
  <div class="row g-2 mb-3">
    <div class="col-sm-5">
      <label class="form-label" for="firstName">First name</label>
      <input class="form-control {{#if errors.firstName}}is-invalid{{/if}}" id="firstName" name="firstName"
             value="{{values.firstName}}" maxlength="30" required>
      {{#if errors.firstName}}<div class="invalid-feedback">{{errors.firstName}}</div>{{/if}}
    </div>
    <div class="col-sm-5">
      <label class="form-label" for="lastName">Last name</label>
      <input class="form-control {{#if errors.lastName}}is-invalid{{/if}}" id="lastName" name="lastName"
             value="{{values.lastName}}" maxlength="30" required>
      {{#if errors.lastName}}<div class="invalid-feedback">{{errors.lastName}}</div>{{/if}}
    </div>
    <div class="col-sm-2">
      <label class="form-label" for="age">Age</label>
      <input class="form-control {{#if errors.age}}is-invalid{{/if}}" id="age" name="age" type="number"
             value="{{values.age}}" required>
      {{#if errors.age}}<div class="invalid-feedback">{{errors.age}}</div>{{/if}}
    </div>
  </div>
  <button class="btn btn-primary" type="submit">Save</button>
  <a class="btn btn-link" href="/persons">Back to the list</a>
</form>

第 4 行:携带记录版本的隐藏字段。该视图既用于添加记录,也用于修改记录:它的标题和提交 URL([action])由控制器提供。视图 [list.hbs] 和 [layout.hbs],以及确认脚本,与示例 20 和 21 中的相同。

9.1.7. 执行

如果默认值不合适,连接参数通过环境变量传递。在 [Windows] ([PowerShell])下:

$env:DB_USERNAME="root"; $env:DB_PASSWORD=""; $env:DB_LOGGING="true"; npx nest start

列表:

Image

无效的表单:

Image

一个同名人员,用小写且不带重音书写:业务规则能检测出来,因为 MySQL 按数据库的排序规则进行比较:

Image

一次成功的添加,以及相应的 SQL 命令([DB_LOGGING=true]):

Image

1
2
3
4
5
6
query: START TRANSACTION
query: SELECT `Person`.`id` AS `Person_id`, `Person`.`version` AS `Person_version`, `Person`.`first_name` AS `Person_first_name`, `Person`.`last_name` AS `Person_last_name`, `Person`.`age` AS `Person_age` FROM `persons` `Person` WHERE ((`Person`.`first_name` = ?) AND (`Person`.`last_name` = ?) AND (`Person`.`id` != ?)) LIMIT 1 -- PARAMETERS: ["Sylvie","Durand",0]
query: INSERT INTO `persons`(`id`, `version`, `first_name`, `last_name`, `age`) VALUES (DEFAULT, 1, ?, ?, ?) -- PARAMETERS: ["Sylvie","Durand",29]
query: SELECT `Person`.`id` AS `Person_id`, `Person`.`version` AS `Person_version` FROM `persons` `Person` WHERE `Person`.`id` = ? -- PARAMETERS: [4]
query: COMMIT
query: SELECT `Person`.`id` AS `Person_id`, `Person`.`version` AS `Person_version`, `Person`.`first_name` AS `Person_first_name`, `Person`.`last_name` AS `Person_last_name`, `Person`.`age` AS `Person_age` FROM `persons` `Person` ORDER BY `Person`.`last_name` ASC, `Person`.`first_name` ASC

我们可以看到事务([START TRANSACTION] …… [COMMIT])、重复检查、版本为 1 的插入,然后是重定向之后对列表的读取。乐观锁:两个表单同时打开同一条记录;第一个被保存(版本变为 2);第二个仍然是版本 1,因此被拒绝:

Image

删除,带确认:

Image

Image