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]:
| // 业务规则拒绝了该操作:这不是异常情况,
// 消息是给用户看的
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
|
列表:

无效的表单:

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

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

| 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,因此被拒绝:

删除,带确认:

