入门指南

简介

¥Introduction

MikroORM 是基于数据映射器、工作单元和身份映射模式的 Node.js 的 TypeScript ORM。在本指南中，你将了解这些词的含义、如何设置一个简单的 API 项目、如何测试它等等。

¥MikroORM is a TypeScript ORM for Node.js based on Data Mapper, Unit of Work, and Identity Map patterns. In this guide, you will learn what those words mean, how to set up a simple API project, how to test it, and many more.

本入门指南以分步教程的形式编写，并附带可用的 StackBlitz 示例和 包含最终项目的 GitHub 存储库。它将向你展示如何从头开始创建可用于生产的应用，一直到你可以部署到任何地方的 docker 镜像。

¥This Getting Started Guide was written as a step-by-step tutorial, accompanied by working StackBlitz examples and a GitHub repository with the final project. It will show you how to create a production-ready application from scratch, all the way down to a docker image you can deploy wherever you want.

要查看我们将要构建的最终项目，请尝试克隆 mikro-orm/guide GitHub 项目。

¥To take a peek at the final project we will be building, try cloning the mikro-orm/guide GitHub project.

git clone https://github.com/mikro-orm/guide.git

信息

本指南重点介绍使用 "代码优先" 方法来开发应用，但 MikroORM 也可以使用 "架构优先" 方法。查看 "架构优先" 指南 以了解更多详细信息。

¥This guide focuses on "code first" approach to developing the application, but MikroORM can also be used with a "schema first" approach. Check out the "schema first" guide for more details on that.

堆栈

¥The Stack

本指南的目标是展示 MikroORM 的最重要功能以及一些更小众的功能。它将引导你使用以下技术为博客创建一个简单的 API：

¥The goal of this guide is to show off the most important features of MikroORM as well as some of the more niche ones. It will walk you through creating a simple API for a blog, with the following technologies:

• MikroORM 带有 SQLite 驱动程序

  ¥MikroORM with SQLite driver

• Fastify 作为 Web 框架

  ¥Fastify as the web framework

• Vitest 用于测试

  ¥Vitest for testing

• ECMAScript 模块

  ¥ECMAScript modules

• JWT 身份验证

  ¥JWT authentication

• 通过 ts-morph 反射

  ¥reflection via ts-morph

MikroORM monorepo

ORM 由几个包组成，我们将使用重要的包：

¥The ORM consists of several packages, the important ones we will be using:

• @mikro-orm/core：包含 ORM 代码的主包

  ¥@mikro-orm/core: the main package with the ORM code

• @mikro-orm/cli：CLI 包，需要在本地安装

  ¥@mikro-orm/cli: the CLI package, needs to be installed locally

• @mikro-orm/sqlite：sqlite 驱动程序包（你也可以使用其他驱动程序）

  ¥@mikro-orm/sqlite: the sqlite driver package (you can use a different driver too)

• @mikro-orm/reflection：要使用 ts-morph 反射启用 DRY 实体

  ¥@mikro-orm/reflection: to enable DRY entities with ts-morph reflection

• @mikro-orm/migrations：用于管理架构迁移的包

  ¥@mikro-orm/migrations: package for managing schema migrations

• @mikro-orm/seeder：用于使用测试数据播种数据库的包

  ¥@mikro-orm/seeder: package for seeding the database with testing data

core 和驱动程序包是必需的，此列表的其余部分是可选的，如果你愿意，可以是开发依赖。我们将使用 sqlite 驱动程序，主要是为了简单起见，因为它不需要任何额外的设置并提供一个方便的内存数据库，我们将在测试中使用它。

¥The core and driver packages are required, the rest of this list is optional and can be a dev dependency if you wish. We will use the sqlite driver, mainly for simplicity, as it does not require any additional setup and offers a handy in-memory database, which we will use in the tests.

还有更多软件包，有些也存在于 mikro-orm/mikro-orm monorepo 之外，例如 @mikro-orm/nestjs 或 @mikro-orm/sql-highlighter - 与 monorepo 中的不同，它们通常具有不同的版本控制线。

¥There are more packages, some also live outside the mikro-orm/mikro-orm monorepo, such as the @mikro-orm/nestjs or @mikro-orm/sql-highlighter - unlike the ones from the monorepo, those usually have different versioning line.

信息

当前可用驱动程序的完整列表：

¥Full list of currently available drivers:

• @mikro-orm/mysql

• @mikro-orm/mariadb

• @mikro-orm/postgresql

• @mikro-orm/sqlite

• @mikro-orm/libsql

• @mikro-orm/better-sqlite

• @mikro-orm/mssql

• @mikro-orm/mongodb

我们在构建什么？

¥What are we building?

我们已经提到了将使用哪些技术，现在详细介绍了该项目。它将是一个简单的博客 API，具有身份验证、发布和评论功能。为此，我们将使用四个常规实体：User、Article、Comment 和 Tag。稍后，我们将添加另一个实体 ArticleListing，这是一个由 SQL 表达式而不是数据库表表示的虚拟实体。

¥We already mentioned what technologies will be used, and now more about the project. It will be a simple API for a blog, with authentication, publishing, and commenting. For that, we will use four regular entities: User, Article, Comment, and Tag. Later on, we will add one more entity, ArticleListing, a virtual entity represented by an SQL expression rather than a database table.

API 路由描述：

¥And the API routes description:

方法	URL	描述
POST	/user/sign-up	注册新用户
POST	/user/sign-in	登录现有用户
GET	/user/profile	获取你的完整个人资料信息
PATCH	/user/profile	修改你的个人资料
POST	/article	创建新文章
GET	/article	列出现有文章
GET	/article/:slug	获取文章详细信息
PATCH	/article/:slug	修改现有文章
DELETE	/article/:slug	删除现有文章
POST	/article/:slug/comment	对现有文章发表评论

代码将被构建为自包含模块：user、article 和 common（用于共享助手）。

¥The code will be structured into self-contained modules: user, article, and common (for shared helpers).

该应用将使用 Node.js 20、TypeScript 5.2，我们将使用启用了 ECMAScript 模块的现代堆栈来构建它。

¥The app will be using Node.js 20, TypeScript 5.2, and we will build it using a modern stack with ECMAScript modules enabled.

我们将涵盖哪些内容

¥What will we cover

以下是你将在本指南中尝试的功能（不完整）列表。

¥Here is (an incomplete) list of features you will try going through this guide.

• 使用 TypeScript 设置从头开始创建应用

  ¥creating an app from scratch with TypeScript setup

• 基于文件夹的发现、ts-morph 反射、ES 模块

  ¥folder-based discovery, ts-morph reflection, ES modules

• 通过中间件/fastify 钩子请求上下文管理

  ¥request context management via middleware/fastify hook

• 实体关系，高级实体定义（例如，惰性标量属性）

  ¥entity relations, advanced entity definition (e.g. lazy scalar properties)

• 高级类型安全（例如 OptionalProps、Reference 封装器和 Loaded 类型）

  ¥advanced type safety (e.g. OptionalProps, Reference wrapper and Loaded type)

• 事件，包括通过 onFlush 事件进行软删除等高级用例

  ¥events, including advanced use cases like soft-delete via onFlush event

• 通过 vitest 进行基本测试

  ¥basic testing via vitest

• 自定义存储库

  ¥custom repositories

• 虚拟实体

  ¥virtual entities

• serialization

• embeddables