数据模型（Model）

总览

数据模型（Model）用于描述业务域对象，例如：Customer（客户），Address（地址），Order（订单）。它通常用使用名字、类型以及其他约束，来定义一系列属性（Property）。

数据模型（Model）可以用于线上数据交换，也可以用于不同系统的数据交换。 例如，一个 JSON 对象符合Customer（客户）数据模型的定义，它可以在 REST/HTTP 负载中上传，以用于创建一个新的客户，或者存储到文档或数据库（例如 MongoDB）。数据模型的定义可以被映射到其他格式，例如：关系型数据库的架构（Schema）, XML 架构，JSON 架构，OpenAPI 架构，gRPC 信息（Message）定义，也可以从这些格式映射到数据模型。

数据模型的域对象有 2 种不同类型的：

• 值对象（Value Object）：没有标识（Identity、ID）的域对象。依据构造的值来判断是否等同。例如，Address（地址）可以被建模为一个值对象，因为当两个地址有同样的城市、街道名、街道号码、和邮政编码，那么它们是等同的。 示例如下：

{
  "name": "Address",
  "properties": {
    "streetNum": "string",
    "streetName": "string",
    "city": "string",
    "zipCode": "string"
  }
}

• 实体（Entity）：有标识（Identity、ID）的域对象。依据标识来判断是否等同。 例如，Customer可以被建模为一个实体，因为每个客户有一个唯一的标识（id）。Customer的两个拥有相同标识（id）的实例是相等的，因为它们引用自同一个客户。 示例如下：

{
  "name": "Customer",
  "properties": {
    "id": "string",
    "lastName": "string",
    "firstName": "string",
    "email": "string",
    "address": "Address"
  }
}

目前，我们提供了@loopback/repository模块，它提供了一些特殊的修饰符，可以添加元数据到你的 TypeScript 或 JavaScript 类，用来实现传统的数据源映射（Datasource Juggler）。

定义数据模型

作为其核心，LoopBack 中的数据模型，是一个简单的 JavaScript 类。

export class Customer {
  email: string;
  isMember: boolean;
  cart: ShoppingCart;
}

可扩展性，是 LoopBack 的核心特征。外部的包可以添加额外的特征，例如，与“映射桥（juggler bridge）”或“JSON 架构生成器”集成。通过@loopback/repository模块的@model和@property修饰符，使这些特征可以用于 LoopBack 数据模型。

import { model, property } from "@loopback/repository";

@model()
export class Customer {
  @property()
  email: string;
  @property()
  isMember: boolean;
  @property()
  cart: ShoppingCart;
}

数据模型发现（Model Discovery）

通过探索（discovering）你的数据库架构，LoopBack 可以自动生成数据模型。 查阅数据模型发现（Discovering models）以了解更多信息，以及支持数据模型发现的连接器的列表。

使用映射桥（Juggler Bridge）

以如下方式定义一个使用映射桥的数据模型：从Entity（实体）扩展你的类，为域对象添加@model和@property修饰符。

import { model, property, Entity } from "@loopback/repository";

@model()
export class Product extends Entity {
  @property({
    id: true,
    description: "The unique identifier for a product"
  })
  id: number;

  @property()
  name: string;

  @property()
  slug: string;

  constructor(data?: Partial<Product>) {
    super(data);
  }
}

数据模型主要以 TypeScript 的类定义。默认情况下，类禁止使用未指明类型定义的额外属性。持久层（Persistence Layer）尊抽这一约束，配置底层 PersistedModel（持久数据模型）类以强制strict模式。

创建一个既明确、又使用“任意额外属性”的数据模型，你需要通过 CLI 在数据模型设置中禁用strict模式，并且在数据模型的实例中告诉 TypeScript 允许“任意额外属性”。

@model({ settings: { strict: false } })
class MyFlexibleModel extends Entity {
  @property({ id: true })
  id: number;

  // 在此处定义明确的属性。

  // 添加一个索引属性，以允许额外数据。
  [prop: string]: any;
}

数据模型修饰符

可以使用无参数的数据模型修饰符，也可以为修饰符传递 ModelDefinitionSyntax（数据模型定义语法）：

@model({
  name: "Category",
  settings: {
    // 省略...
  }
  // 在下面使用@property修饰符
})
class Category extends Entity {
  // 省略...
  @property({ type: "number" })
  categoryId: number;
}

数据模型修饰符知道你的数据模型类的名字，你可以略去它。

@model()
class Product extends Entity {
  name: string;
  // 其他属性...
}

然而，数据模型修饰符在 LoopBack 4 和 LoopBack 3 中不完全相同。 例如，在lb3中，我们可以在数据模型修饰符中传递一个数据模型定义语法，就像属性、选项、关系等。但是这些项在 LooopBack 4 的数据模型修饰符中并不都是可用的。

注意：在 LoopBack 4 中，我们当前在 ModelDefinitionSyntax 中仅支持settings。LoopBack 3 中的那些top-level properties（顶级属性）现在在settings中传递。

• properties现在在 @property修饰符中定义（查看下面内容以获得更多信息）。
• LoopBack 3 中的options，在 LoopBack 4 中，还没有映射特征。（查看issue #2142中的进一步讨论）

settings的实体中，现在 LoopBack 4 支持下列内置实体：

支持的 Settings 实体

​

不支持的 Settings 实体

@model() class MySuperModel extends MyBaseModel {...}
      

更多关于 LoopBack 4 中Model Decorator（数据模型修饰符）的信息，请查阅 legacy-juggler-bridge file 和 model-builder file.

属性修饰符

属性修饰符与 LoopBack 3 的属性使用同样的参数。

对于每一个属性项，属性修饰符为它定义一些属性，示例如下：

@model()
class Product extends Entity {
  @property({
    name: "name",
    description: "The product's common name.",
    type: "string"
  })
  public name: string;

  @property({
    type: "number",
    id: true
  })
  id: number;
}

属性的基本属性

每一个数据模型的属性，都有一些以关键字（Key）定义的属性用于描述，详见下表。只有type（类型）属性是必须的；对于只有type属性的属性，你可以使用下面示例的快速写法：

"propertyName": "type"

例如：

...
"emailVerified": "boolean",
"status": "string",
...

属性关键字列表：

[
            "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
            "sed do eiusmod tempor incididunt ut labore et dolore",
            "magna aliqua."
            ]
        

ID 属性

代表数据库中的持久数据的数据模型，通常有一个或多个 ID 属性，可以唯一标识出此数据库模型的每个实例。 例如：user数据模型可以包含用户的 ID（标识符）。

默认情况下，如果没有定义 ID 属性，同时idInjection属性为true（或者没有设置，true 是默认值），LoopBack 会自动为数据模型添加id属性，如下所示：

id: {type: Number, generated: true, id: true}

generated 属性表明，此 ID 是否由数据库自动生成。 如果为true，连接器（Connector）将决定自动生成的 ID 的数据类型。对于关系型数据库来说（例如 Oracle 或 MySQL），它的默认类型是number。 如果你的应用会生成 ID，设置此属性为false。

为了明确指明某个属性是 ID，须设置此属性的id属性为true。id属性的值必须是下列之一：

• true：此属性是一个 ID。
• false（或者任何会被转换成 false 的值）：此属性不是一个 ID，此项为默认值。
• 正整数（例如 1 或者 2）：此属性是一个复合 ID 的索引（index）。

在数据库术语中，ID 属性是主键列。此类id属性被设置为true，或一个表示复合键顺序的正整数。

例如：

{
  "myId": {
    "type": "string",
    "id": true
   }
}

重要：

1. 如果一个数据模型没有明确定义的 ID 属性，LoopBack 会自动注入一个名为“id”的属性作为标识符，除非idInjection选项被设置为false。
2. 如果一个 ID 属性的generated设置为true，连接器（Connector）将决定自动生成的 ID 的数据类型。对于关系型数据库来说（例如 Oracle 或 MySQL），它的默认类型是number。
3. 如果数据模型需要支持数据库，LoopBack 的 CRUD 方法需要此数据模型拥有一个“id”属性。
4. 没有任何“id”属性的数据模型，只能在无关数据库处使用。

复合 ID

LoopBack 支持定义由“多个属性”组成的复合 ID，示例如下：

var InventoryDefinition = {
  productId: { type: String, id: 1 },
  locationId: { type: String, id: 2 },
  qty: Number
};

这个复合 ID 是(productId, locationId)，用于一个库存数据模型。

数据映射属性

当使用关系型数据库作为数据源时，你可以使用下列属性来描述数据库中的列。

要映射一个属性到一个 Oracle 数据库的表的一列，示例如下：

...
"name": {
      "type": "String",
      "required": false,
      "length": 40,
      "oracle": {
        "columnName": "NAME",
        "dataType": "VARCHAR2",
        "dataLength": 40,
        "nullable": "Y"
      }
    }
...

  <table>
    <tbody>
      <tr>
        <th>关键字</th>
        <th>类型</th>
        <th>描述</th>
      </tr>
      <tr>
        <td>trim</td>
        <td>Boolean</td>
        <td>是否修剪（Trim）字符串</td>
      </tr>
      <tr>
        <td>lowercase</td>
        <td>Boolean</td>
        <td>是否转换字符串为小写</td>
      </tr>
      <tr>
        <td>uppercase</td>
        <td>Boolean</td>
        <td>是否转换字符串为大写</td>
      </tr>
      <tr>
        <td>format</td>
        <td>Regular expression</td>
        <td>正则表达式，用于格式化日期属性。</td>
      </tr>
    </tbody>
  </table>
</div>

...
"base": "User",
"excludeBaseProperties" = ["lastUpdated", "credentials", "challenges"],
"properties": {
  ...
}
...

...
"base": "Model",
"excludeBaseProperties" = ["id"],
"properties": {
  ...
}
...

...
"base": "User",
"properties": {
  "lastUpdated": false,
  "credentials": null,
  "challenges": null,
  "modified": "date"
}
...

@model({
  settings: {
    hiddenProperties: ['password']
  }
})
class MyUserModel extends Entity {
  @property({id: true})
  id: number;
   @property({type: 'string'})
  email: string;
   @property({type: 'string'})
  password: string;
  ...
}

{
  ...
  "properties": {
    ...
    "email": {
      "type": "string",
      "required": true
    },
    ...
  },
  "protected": ["email"],
  ...
}

@model()
class Product extends Entity {
  @property({
    name: "name",
    description: "The product's common name.",
    type: "string",
    // 在此定义JSON的验证规则
    jsonSchema: {
      maxLength: 30,
      minLength: 10
    }
  })
  public name: string;
}

@model()
class Product extends Entity {
  @property()
  public name: string; // 此属性的类型信息是string（字符串）
}

@model()
class Order extends Entity {
  @property.array(Product)
  items: Product[];
}

@model()
class Thread extends Entity {
  // 注意，即使是原始类型，我们仍然需要设置数组属性！
  @property.array(String)
  posts: string[];
}

@model()
class Customer extends Entity {
  @property.array(String, {
    name: "names",
    required: true
  })
  aliases: string[];
}

import { model, property } from "@loopback/repository";
import { getJsonSchema } from "@loopback/repository-json-schema";

@model()
class Category {
  @property()
  name: string;
}

@model()
class Product {
  @property({ required: true })
  name: string;
  @property()
  type: Category;
}

const jsonSchema = getJsonSchema(Product);

{
  "title": "Product",
  "properties": {
    "name": {
      "type": "string"
    },
    "type": {
      "$ref": "#/definitions/Category"
    }
  },
  "definitions": {
    "Category": {
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": ["name"]
}