# 实体
* [实体是什么?](#实体是什么)
* [实体列](#实体列)
* [主列](#主列)
* [特殊列](#特殊列)
* [空间列](#空间列)
* [列类型](#列类型)
* [`mysql`/`mariadb`的列类型](#`mysql`/`mariadb`的列类型)
* [`postgres`的列类型](#`postgres`的列类型)
* [`sqlite`/`cordova`/`react-native`/`expo`的列类型](#sqlite`/`cordova`/`react-native`/`expo`的列类型)
* [`mssql`的列类型](#`mssql`的列类型)
* [`oracle`的列类型](#`oracle`的列类型)
* [`enum`列类型](#`enum`列类型)
* [`simple-array`的列类型](#`simple-array`的列类型)
* [`simple-json`列类型](#`simple-json`列类型)
* [具有生成值的列](#具有生成值的列)
* [列选项](#列选项)
## 实体是什么?
实体是一个映射到数据库表（或使用 MongoDB 时的集合）的类。
你可以通过定义一个新类来创建一个实体，并用`@Entity()`来标记：
```typescript
import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number;
@Column()
firstName: string;
@Column()
lastName: string;
@Column()
isActive: boolean;
}
```
这将创建以下数据库表：
```bash
+-------------+--------------+----------------------------+
| user |
+-------------+--------------+----------------------------+
| id | int(11) | PRIMARY KEY AUTO_INCREMENT |
| firstName | varchar(255) | |
| lastName | varchar(255) | |
| isActive | boolean | |
+-------------+--------------+----------------------------+
```
基本实体由列和关系组成。
每个实体**必须**有一个主列（如果使用 MongoDB，则为 ObjectId 列）。
每个实体都必须在连接选项中注册：
```typescript
import { createConnection, Connection } from "typeorm";
import { User } from "./entity/User";
const connection: Connection = await createConnection({
type: "mysql",
host: "localhost",
port: 3306,
username: "test",
password: "test",
database: "test",
entities: [User]
});
```
或者你可以指定包含所有实体的整个目录， 该目录下所有实体都将被加载：
```typescript
import { createConnection, Connection } from "typeorm";
const connection: Connection = await createConnection({
type: "mysql",
host: "localhost",
port: 3306,
username: "test",
password: "test",
database: "test",
entities: ["entity/*.js"]
});
```
如果要为`User`实体使用替代表名，可以在`@ Entity`中指定：`@Entity（“my_users”）`。
如果要为应用程序中的所有数据库表设置基本前缀，可以在连接选项中指定`entityPrefix`。
使用实体构造函数时，其参数**必须是可选的**。 由于 ORM 在从数据库加载时才创建实体类的实例，因此在此之前并不知道构造函数的参数。
在[Decorators reference](decorator-reference.md)中了解有关参数@Entity 的更多信息。
## 实体列
由于数据库表由列组成，因此实体也必须由列组成。
标有`@ Column`的每个实体类属性都将映射到数据库表列。
### 主列
每个实体必须至少有一个主列。
有几种类型的主要列：
- `@PrimaryColumn()` 创建一个主列，它可以获取任何类型的任何值。你也可以指定列类型。 如果未指定列类型，则将从属性类型自动推断。
下面的示例将使用`int`类型创建 id，你必须在保存之前手动分配。
```typescript
import { Entity, PrimaryColumn } from "typeorm";
@Entity()
export class User {
@PrimaryColumn()
id: number;
}
```
- `@PrimaryGeneratedColumn()` 创建一个主列，该值将使用自动增量值自动生成。 它将使用`auto-increment` /`serial` /`sequence`创建`int`列（取决于数据库）。 你不必在保存之前手动分配其值，该值将会自动生成。
```typescript
import { Entity, PrimaryGeneratedColumn } from "typeorm";
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number;
}
```
- `@PrimaryGeneratedColumn("uuid")` 创建一个主列，该值将使用`uuid`自动生成。 Uuid 是一个独特的字符串 id。 你不必在保存之前手动分配其值，该值将自动生成。
```typescript
import { Entity, PrimaryGeneratedColumn } from "typeorm";
@Entity()
export class User {
@PrimaryGeneratedColumn("uuid")
id: string;
}
```
你也可以拥有复合主列：
```typescript
import { Entity, PrimaryColumn } from "typeorm";
@Entity()
export class User {
@PrimaryColumn()
firstName: string;
@PrimaryColumn()
lastName: string;
}
```
当您使用`save`保存实体时，它总是先尝试使用给定的实体 ID（或 ids）在数据库中查找实体。
如果找到 id / ids，则将更新数据库中的这一行。
如果没有包含 id / ids 的行，则会插入一个新行。
要通过 id 查找实体，可以使用`manager.findOne`或`repository.findOne`。 例：
```typescript
// 使用单个主键查找一个id
const person = await connection.manager.findOne(Person, 1);
const person = await connection.getRepository(Person).findOne(1);
// 使用复合主键找到一个id
const user = await connection.manager.findOne(User, { firstName: "Timber", lastName: "Saw" });
const user = await connection.getRepository(User).findOne({ firstName: "Timber", lastName: "Saw" });
```
### 特殊列
有几种特殊的列类型可以使用：
- `@CreateDateColumn` 是一个特殊列，自动为实体插入日期。无需设置此列，该值将自动设置。
- `@UpdateDateColumn` 是一个特殊列，在每次调用实体管理器或存储库的`save`时，自动更新实体日期。无需设置此列，该值将自动设置。
- `@VersionColumn` 是一个特殊列，在每次调用实体管理器或存储库的`save`时自动增长实体版本（增量编号）。无需设置此列，该值将自动设置。
### 空间列
MS SQL，MySQL/MariaDB 和 PostgreSQL 都支持 Spatial 列。由于各数据库列名不同，TypeORM 对数据库的支持略有差异。
MS SQL 和 MySQL/MariaDB 的 TypeORM 支持[well-known text(WKT)](https://en.wikipedia.org/wiki/Well-known_text)的 geometries，因此 geometry 列 应该是用`string`类型标记。
TypeORM 的 PostgreSQL 支持使用[GeoJSON](http://geojson.org/)作为交换格式，因此 geometry 列应在导入后标记为`object`或`Geometry`（或子类，例如`Point`）。
TypeORM尝试做正确的事情，但并不总是能够确定何时插入的值或PostGIS函数的结果应被视为几何。 因此，你可能会发现自己编写的代码类似于以下代码，其中值从GeoJSON转换为PostGIS `geometry`,并作为`json`转换为GeoJSON：
```typescript
const origin = {
type: "Point",
coordinates: [0, 0]
};
await getManager()
.createQueryBuilder(Thing, "thing")
// 将字符串化的GeoJSON转换为具有与表规范匹配的SRID的geometry
.where("ST_Distance(geom, ST_SetSRID(ST_GeomFromGeoJSON(:origin), ST_SRID(geom))) > 0")
.orderBy({
"ST_Distance(geom, ST_SetSRID(ST_GeomFromGeoJSON(:origin), ST_SRID(geom)))": {
order: "ASC"
}
})
.setParameters({
// 字符串化 GeoJSON
origin: JSON.stringify(origin)
})
.getMany();
await getManager()
.createQueryBuilder(Thing, "thing")
// 将geometry结果转换为GeoJSON，以将此视为JSON（以便TypeORM知道反序列化它）
.select("ST_AsGeoJSON(ST_Buffer(geom, 0.1))::json geom")
.from("thing")
.getMany();
```
## 列类型
TypeORM 支持所有最常用的数据库支持的列类型。
列类型是特定于数据库类型的 - 这为数据库架构提供了更大的灵活性。
你可以将列类型指定为`@ Column`的第一个参数
或者在`@Column`的列选项中指定，例如：
```typescript
@Column("int")
```
或
```typescript
@Column({ type: "int" })
```
如果要指定其他类型参数，可以通过列选项来执行。
例如:
```typescript
@Column("varchar", { length: 200 })
```
或
```typescript
@Column({ type: "int", length: 200 })
```
### `mysql`/`mariadb`的列类型
`int`, `tinyint`, `smallint`, `mediumint`, `bigint`, `float`, `double`, `dec`, `decimal`, `numeric`,
`date`, `datetime`, `timestamp`, `time`, `year`, `char`, `varchar`, `nvarchar`, `text`, `tinytext`,
`mediumtext`, `blob`, `longtext`, `tinyblob`, `mediumblob`, `longblob`, `enum`, `json`, `binary`,
`geometry`, `point`, `linestring`, `polygon`, `multipoint`, `multilinestring`, `multipolygon`,
`geometrycollection`
### `postgres`的列类型
`int`, `int2`, `int4`, `int8`, `smallint`, `integer`, `bigint`, `decimal`, `numeric`, `real`,
`float`, `float4`, `float8`, `double precision`, `money`, `character varying`, `varchar`,
`character`, `char`, `text`, `citext`, `hstore`, `bytea`, `bit`, `varbit`, `bit varying`,
`timetz`, `timestamptz`, `timestamp`, `timestamp without time zone`, `timestamp with time zone`,
`date`, `time`, `time without time zone`, `time with time zone`, `interval`, `bool`, `boolean`,
`enum`, `point`, `line`, `lseg`, `box`, `path`, `polygon`, `circle`, `cidr`, `inet`, `macaddr`,
`tsvector`, `tsquery`, `uuid`, `xml`, `json`, `jsonb`, `int4range`, `int8range`, `numrange`,
`tsrange`, `tstzrange`, `daterange`, `geometry`, `geography`
### `sqlite`/`cordova`/`react-native`/`expo`的列类型
`int`, `int2`, `int8`, `integer`, `tinyint`, `smallint`, `mediumint`, `bigint`, `decimal`,
`numeric`, `float`, `double`, `real`, `double precision`, `datetime`, `varying character`,
`character`, `native character`, `varchar`, `nchar`, `nvarchar2`, `unsigned big int`, `boolean`,
`blob`, `text`, `clob`, `date`
### `mssql`的列类型
`int`, `bigint`, `bit`, `decimal`, `money`, `numeric`, `smallint`, `smallmoney`, `tinyint`, `float`,
`real`, `date`, `datetime2`, `datetime`, `datetimeoffset`, `smalldatetime`, `time`, `char`, `varchar`,
`text`, `nchar`, `nvarchar`, `ntext`, `binary`, `image`, `varbinary`, `hierarchyid`, `sql_variant`,
`timestamp`, `uniqueidentifier`, `xml`, `geometry`, `geography`, `rowversion`
### `oracle`的列类型
`char`, `nchar`, `nvarchar2`, `varchar2`, `long`, `raw`, `long raw`, `number`, `numeric`, `float`, `dec`,
`decimal`, `integer`, `int`, `smallint`, `real`, `double precision`, `date`, `timestamp`, `timestamp with time zone`,
`timestamp with local time zone`, `interval year to month`, `interval day to second`, `bfile`, `blob`, `clob`,
`nclob`, `rowid`, `urowid`
### `enum` 列类型
`postgres`和`mysql`都支持`enum`列类型。 并有多种列定义方式：
使用typescript枚举：
```typescript
export enum UserRole {
ADMIN = "admin",
EDITOR = "editor",
GHOST = "ghost"
}
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number;
@Column({
type: "enum",
enum: UserRole,
default: UserRole.GHOST
})
role: UserRole
}
```
> 注意：支持字符串，数字和异构枚举。
使用带枚举值的数组：
```typescript
export type UserRoleType = "admin" | "editor" | "ghost",
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number;
@Column({
type: "enum",
enum: ["admin", "editor", "ghost"],
default: "ghost"
})
role: UserRoleType
}
```
### `simple-array` column type
`postgres`和`mysql`支持`enum`列类型。 有多种列定义方式：
使用 typescript 枚举:
```typescript
export enum UserRole {
ADMIN = "admin",
EDITOR = "editor"
GHOST = "ghost"
}
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number;
@Column({
type: "enum",
enum: UserRole,
default: UserRole.GHOST
})
role: UserRole
}
```
> 注意：支持字符串，数字和异构枚举。
> 使用带枚举值的数组：
```typescript
export type UserRoleType = "admin" | "editor" | "ghost",
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number;
@Column({
type: "enum",
enum: ["admin", "editor", "ghost"],
default: "ghost"
})
role: UserRoleType
}
```
### `simple-array`的列类型
有一种称为`simple-array`的特殊列类型，它可以将原始数组值存储在单个字符串列中。
所有值都以逗号分隔。 例如：
```typescript
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number;
@Column("simple-array")
names: string[];
}
```
```typescript
const user = new User();
user.names = ["Alexander", "Alex", "Sasha", "Shurik"];
```
存储在单个数据库列中的`Alexander，Alex，Sasha，Shurik`值。
当你从数据库加载数据时，name 将作为 names 数组返回，就像之前存储它们一样。
注意**不能**在值里面有任何逗号。
### `simple-json` 列类型
还有一个名为`simple-json`的特殊列类型，它可以存储任何可以通过 JSON.stringify 存储在数据库中的值。
当你的数据库中没有 json 类型而你又想存储和加载对象，该类型就很有用了。
例如:
```typescript
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number;
@Column("simple-json")
profile: { name: string; nickname: string };
}
```
```typescript
const user = new User();
user.profile = { name: "John", nickname: "Malkovich" };
```
存储在单个数据库列中的`{“name”：“John”，“nickname”：“Malkovich”}`值
当你从数据库加载数据时，将通过 JSON.parse 返回 object/array/primitive。
### 具有生成值的列
你可以使用`@Generated`装饰器创建具有生成值的列。 例如：
```typescript
@Entity()
export class User {
@PrimaryColumn()
id: number;
@Column()
@Generated("uuid")
uuid: string;
}
```
`uuid`值将自动生成并存储到数据库中。
除了"uuid"之外，还有"increment"生成类型，但是对于这种类型的生成，某些数据库平台存在一些限制（例如，某些数据库只能有一个增量列，或者其中一些需要增量才能成为主键）。
## 列选项
列选项定义实体列的其他选项。
你可以在`@ Column`上指定列选项：
```typescript
@Column({
type: "varchar",
length: 150,
unique: true,
// ...
})
name: string;
```
`ColumnOptions`中可用选项列表：
- `type: ColumnType` - 列类型。其中之一在[上面](#column-types).
- `name: string` - 数据库表中的列名。
默认情况下，列名称是从属性的名称生成的。
你也可以通过指定自己的名称来更改它。
- `length: number` - 列类型的长度。 例如，如果要创建`varchar（150）`类型，请指定列类型和长度选项。
- `width: number` - 列类型的显示范围。 仅用于[MySQL integer types](https://dev.mysql.com/doc/refman/5.7/en/integer-types.html)
- `onUpdate: string` - `ON UPDATE`触发器。 仅用于 [MySQL](https://dev.mysql.com/doc/refman/5.7/en/timestamp-initialization.html).
- `nullable: boolean` - 在数据库中使列`NULL`或`NOT NULL`。 默认情况下，列是`nullable：false`。
- `update: boolean` - 指示"save"操作是否更新列值。如果为false，则只能在第一次插入对象时编写该值。
默认值为"true"。
- `select: boolean` - 定义在进行查询时是否默认隐藏此列。 设置为`false`时，列数据不会显示标准查询。 默认情况下，列是`select：true`
- `default: string` - 添加数据库级列的`DEFAULT`值。
- `primary: boolean` - 将列标记为主要列。 使用方式和`@ PrimaryColumn`相同。
- `unique: boolean` - 将列标记为唯一列（创建唯一约束）。
- `comment: string` - 数据库列备注，并非所有数据库类型都支持。
- `precision: number` - 十进制（精确数字）列的精度（仅适用于十进制列），这是为值存储的最大位数。仅用于某些列类型。
- `scale: number` - 十进制（精确数字）列的比例（仅适用于十进制列），表示小数点右侧的位数，且不得大于精度。 仅用于某些列类型。
- `zerofill: boolean` - 将`ZEROFILL`属性设置为数字列。 仅在 MySQL 中使用。 如果是`true`，MySQL 会自动将`UNSIGNED`属性添加到此列。
- `unsigned: boolean` - 将`UNSIGNED`属性设置为数字列。 仅在 MySQL 中使用。
- `charset: string` - 定义列字符集。 并非所有数据库类型都支持。
- `collation: string` - 定义列排序规则。
- `enum: string[]|AnyEnum` - 在`enum`列类型中使用，以指定允许的枚举值列表。 你也可以指定数组或指定枚举类。
- `asExpression: string` - 生成的列表达式。 仅在[MySQL](https://dev.mysql.com/doc/refman/5.7/en/create-table-generated-columns.html)中使用。
- `generatedType: "VIRTUAL"|"STORED"` - 生成的列类型。 仅在[MySQL](https://dev.mysql.com/doc/refman/5.7/en/create-table-generated-columns.html)中使用。
- `hstoreType: "object"|"string"` -返回`HSTORE`列类型。 以字符串或对象的形式返回值。 仅在[Postgres](<(https://www.postgresql.org/docs/9.6/static/hstore.html)>)中使用。
- `array: boolean` - 用于可以是数组的 postgres 列类型（例如 int []）
- `transformer: { from(value: DatabaseType): EntityType, to(value: EntityType): DatabaseType }` - 用于将任意类型`EntityType`的属性编组为数据库支持的类型`DatabaseType`。
注意：大多数列选项都是特定于 RDBMS 的，并且在`MongoDB`中不可用。
## 实体继承
你可以使用实体继承减少代码中的重复。
例如，你有`Photo`, `Question`, `Post` 三个实体:
```typescript
@Entity()
export class Photo {
@PrimaryGeneratedColumn()
id: number;
@Column()
title: string;
@Column()
description: string;
@Column()
size: string;
}
@Entity()
export class Question {
@PrimaryGeneratedColumn()
id: number;
@Column()
title: string;
@Column()
description: string;
@Column()
answersCount: number;
}
@Entity()
export class Post {
@PrimaryGeneratedColumn()
id: number;
@Column()
title: string;
@Column()
description: string;
@Column()
viewCount: number;
}
```
正如你所看到的，所有这些实体都有共同的列：`id`，`title`，`description`。 为了减少重复并产生更好的抽象，我们可以为它们创建一个名为`Content`的基类：
```typescript
export abstract class Content {
@PrimaryGeneratedColumn()
id: number;
@Column()
title: string;
@Column()
description: string;
}
@Entity()
export class Photo extends Content {
@Column()
size: string;
}
@Entity()
export class Question extends Content {
@Column()
answersCount: number;
}
@Entity()
export class Post extends Content {
@Column()
viewCount: number;
}
```
来自父实体的所有列（relations，embeds 等）（父级也可以扩展其他实体）将在最终实体中继承和创建。
## 树实体
TypeORM 支持存储树结构的 Adjacency 列表和 Closure 表模式。
### 邻接列表
邻接列表是一个具有自引用的简单模型。
这种方法的好处是简单，缺点是你不能因为连接限制而立刻加载一个树实体。
例如:
```typescript
import { Entity, Column, PrimaryGeneratedColumn, ManyToOne, OneToMany } from "typeorm";
@Entity()
export class Category {
@PrimaryGeneratedColumn()
id: number;
@Column()
name: string;
@Column()
description: string;
@OneToMany(type => Category, category => category.children)
parent: Category;
@ManyToOne(type => Category, category => category.parent)
children: Category;
}
```
### Closure 表
closure 表以特殊方式在单独的表中存储父和子之间的关系。
它在读写方面都很有效。
要了解有关 closure 表的更多信息，请查看 [this awesome presentation by Bill Karwin](https://www.slideshare.net/billkarwin/models-for-hierarchical-data).
例如:
```typescript
import { Entity, Tree, Column, PrimaryGeneratedColumn, TreeChildren, TreeParent, TreeLevelColumn } from "typeorm";
@Entity()
@Tree("closure-table")
export class Category {
@PrimaryGeneratedColumn()
id: number;
@Column()
name: string;
@Column()
description: string;
@TreeChildren()
children: Category;
@TreeParent()
parent: Category;
@TreeLevelColumn()
level: number;
}
```
- 快速开始
- 连接
- 使用 ormconfig
- Connection 选项
- 多个 Connection
- Connection API
- 实体
- 嵌入式实体
- 实体继承
- 树实体
- 视图实体
- 分离实体定义
- 关系
- 一对一
- 多对一/一对多的关系
- 多对多的关系
- Eager 和 Lazy 关系
- 关系常见问题
- Entity Manager 和 Repository
- Find 选项
- 自定义存储库
- EntityManager API
- Repository API
- Query Builder
- 使用 Query Builder 插入
- 使用 Query Builder 更新
- 使用 Query Builder 删除
- 与 Relations 结合
- 缓存查询
- 高级主题
- 迁移
- 事务
- 索引
- 实体监听器和订阅者
- 日志
- 使用 CLI
- 故障排除
- 指南
- Active Record 与 Data Mapper
- MongoDB
- 使用 Validation
- 使用 TypeORM 和 Express 的示例
- 使用 JavaScript
- 从 Sequelize 迁移到 TypeORM
- 帮助
- FAQ
- 支持的平台
- 装饰器参考
- 产品路线图
- 支持