Skip to content

Commit 823de60

Browse files
committed
Add Chinese Getting Started guide
Add a new getting-started.md (Chinese) that provides a quick-start for Sequelize v7: installation, connecting to supported databases (Postgres, MySQL, MariaDB, SQLite, MSSQL, DB2, Snowflake), a short SQLite example, testing and closing connections, terminology, TypeScript configuration and module resolution notes, CommonJS vs ESM usage, logging options, and a pointer to defining models as the next step.
1 parent b477ba0 commit 823de60

File tree

1 file changed

+136
-0
lines changed

1 file changed

+136
-0
lines changed

getting-started.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# 快速开始
2+
3+
在本教程中,你将学习如何对 Sequelize 进行一个简单的基础配置。
4+
5+
## 安装
6+
7+
Sequelize 可以通过 [npm](https://www.npmjs.com/package/@sequelize/core)(或 [yarn](https://yarnpkg.com/package/@sequelize/core))安装。
8+
9+
以下命令将安装 Sequelize v7。
10+
如果你在寻找 Sequelize v6(包名为 `sequelize`,而不是 `@sequelize/core`),请
11+
[访问 v6 文档](https://github.com/demopark/sequelize-docs-Zh-CN/tree/v6)
12+
13+
```bash
14+
# 这将安装 Sequelize 7(Sequelize 最新的 alpha 版本)
15+
npm i @sequelize/core@alpha
16+
```
17+
18+
## 连接数据库
19+
20+
要连接数据库,你必须创建一个 Sequelize 实例,并向其传入数据库配置信息,例如方言(dialect)、主机(host)以及用户名和密码。
21+
22+
不同的方言支持的选项集合不同。请通过下面的链接查看如何连接到你的数据库:
23+
24+
- [PostgreSQL](./databases/postgres.md)
25+
- [MySQL](./databases/mysql.md)
26+
- [MariaDB](./databases/mariadb.md)
27+
- [SQLite](./databases/sqlite.md)
28+
- [Microsoft SQL Server](./databases/mssql.md)
29+
- [DB2 for LUW](./databases/db2.md)
30+
- [DB2 for IBM i](./databases/ibmi.md)
31+
- [Snowflake](./databases/snowflake.md)
32+
33+
如果你的数据库未在上方列表中,Sequelize 默认并不直接支持它。
34+
不过 Sequelize 具有可扩展性:你可以创建自己的方言,或寻找社区维护的方言实现。
35+
更多信息请参阅 [支持其他数据库](./databases/new.md)
36+
37+
下面是一个连接 SQLite 数据库的简短示例:
38+
39+
```javascript
40+
import { Sequelize } from '@sequelize/core';
41+
import { SqliteDialect } from '@sequelize/sqlite3';
42+
43+
const sequelize = new Sequelize({
44+
dialect: SqliteDialect,
45+
});
46+
```
47+
48+
`Sequelize` 构造函数接受许多选项。
49+
它们都记录在 [API 参考](https://sequelize.org/api/v7/classes/_sequelize_core.index.Sequelize.html#constructor) 中。
50+
51+
### 测试连接
52+
53+
你可以使用 `.authenticate()` 函数来测试连接是否正常。
54+
注意这完全是可选的,但我们推荐这么做,因为 Sequelize 会在首次连接时获取你的数据库版本。
55+
随后它会使用该版本来判断哪些 SQL 功能可用。
56+
57+
```js
58+
try {
59+
await sequelize.authenticate();
60+
console.log('Connection has been established successfully.');
61+
} catch (error) {
62+
console.error('Unable to connect to the database:', error);
63+
}
64+
```
65+
66+
### 关闭连接
67+
68+
Sequelize 使用连接池来管理数据库连接。这意味着即使你已经不再使用它们,某些连接仍可能保持打开状态。
69+
如果你希望优雅地关闭应用程序,可以使用 [`sequelize.close()`](https://sequelize.org/api/v7/classes/_sequelize_core.index.Sequelize.html#close) 来关闭所有活动连接。
70+
71+
一旦调用了 `sequelize.close()`,就无法再打开新的连接。若要再次访问数据库,你需要创建一个新的 Sequelize 实例。
72+
73+
## 术语约定
74+
75+
请注意,在上面的示例中,`Sequelize` 指的是这个库本身,而小写的 `sequelize` 指的是 Sequelize 的一个实例。
76+
这是我们推荐的命名约定,本文档将始终遵循这一约定。
77+
78+
## TypeScript
79+
80+
Sequelize 提供内置的 TypeScript 支持。
81+
82+
请前往 [版本策略页面](/releases) 了解支持哪些 TypeScript 版本,
83+
并确保你的项目已安装与你的 Node.js 版本相对应的 [`@types/node`](https://www.npmjs.com/package/@types/node) 包。
84+
85+
Sequelize 使用了 `package.json` 中的 [`exports`](https://nodejs.org/api/packages.html#exports) 字段。
86+
你可能需要更新 `tsconfig.json` 配置,以确保 TypeScript 的模块解析支持它。
87+
88+
在撰写本文时(TS 5.4),可以通过两种方式实现:
89+
90+
- Set [`moduleResolution`](https://www.typescriptlang.org/tsconfig#moduleResolution) to `node16`, `nodenext`, or `bundler`,
91+
- 或将 [`resolvePackageJsonExports`](https://www.typescriptlang.org/tsconfig#resolvePackageJsonExports) 设置为 `true`
92+
93+
## CommonJS 还是 ESM?
94+
95+
本文档大量使用 ECMAScript Modules(ESM),但 Sequelize 也完全支持 CommonJS。
96+
要在 CommonJS 项目中使用 Sequelize,只需用 `require` 替代 `import`
97+
98+
```js
99+
// 在 ESM 中如何导入 Sequelize
100+
import { Sequelize, Op, Model, DataTypes } from '@sequelize/core';
101+
102+
// 在 CommonJS 中如何导入 Sequelize
103+
const { Sequelize, Op, Model, DataTypes } = require('@sequelize/core');
104+
```
105+
106+
Sequelize 提供的大多数方法都是异步的,因此会返回 [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
107+
我们强烈建议使用 **ECMAScript Modules**,因为它能让你使用 [Top-Level Await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await),而我们在示例中也大量使用了它。
108+
请参阅 [Node.js 文档](https://nodejs.org/api/esm.html) 了解如何在 Node.js 中使用 ESM。
109+
110+
## 日志
111+
112+
为了便于调试,你可以在 Sequelize 中启用日志。做法是将 `logging` 选项设置为一个函数,每当 Sequelize 需要输出日志时就会执行该函数。
113+
114+
示例:
115+
116+
```js
117+
const sequelize = new Sequelize({
118+
dialect: SqliteDialect,
119+
120+
// 禁用日志(默认)
121+
logging: false,
122+
123+
// 将日志输出到控制台
124+
logging: console.log,
125+
126+
// 你也可以使用任意函数,例如把日志发送到日志工具
127+
logging: (...msg) => console.log(msg),
128+
});
129+
```
130+
131+
如果你只需要记录特定查询,可以在所有会执行查询的模型方法中使用 `logging` 选项,
132+
以及在所有 `queryInterface` 方法中使用它。
133+
134+
## 下一步
135+
136+
现在你已经有了一个 Sequelize 实例,接下来可以从 [定义你的第一个模型](./models/defining-models.md) 开始。

0 commit comments

Comments
 (0)