# 认识 ts-grm

这一页先回答两个问题：**ts-grm 是什么**，以及**这本教程怎么读**。

## ts-grm 是什么

ts-grm 是面向 **TypeScript 7** 的 **GRM（ORM+）**——数据访问框架，Jimmer 的 TypeScript 移植。GRM 是对 ORM 的扩展：不满足于「把表映射成对象」，还覆盖读写、取形、关联、多态、复合值与公式等完整的数据访问需求。

和常见 ORM（Prisma、TypeORM、Sequelize…）相比，ts-grm 的根本差异在三个设计支点：

1. **零代码生成**——`model(...)` 的 class 就是全部元数据，字段类型与可空性从声明直接推断；没有预处理器、没有生成文件、没有运行时反射；
2. **没有实体对象**——查询不返回「实体」，返回视图声明的**精确 DTO**：列表只要两列就只物化两列；没有懒加载魔法与隐藏状态，序列化即所得；
3. **查询即取形，类型即形状**——`dto.view` 像 GraphQL 一样声明要哪些列与关联，返回类型由类型系统推导并在**编译期锁定**：取错字段当场编译失败，而不是运行期才暴露。

一句话总结：**模型描述「表有什么」，视图 / Input 描述「这次要什么」**——框架在两者之间生成最直接的 SQL 与最小可用的 DTO。读侧用 View 取形，写侧用 Input DTO 取形（后者随上游发布中），是「双向的 GraphQL」。

> 想深入这套理念，核心概念章有一整页「[DTO 哲学](/docs/core-concepts/dto-philosophy)」讲为什么可以没有实体对象——那是 ts-grm 与常见 ORM 最大的理念差异。

## 本站：可运行的交互式教程

本站是 ts-grm 的**交互式中文教程**，与框架文档互补：

- 每个概念对应一篇小页，**每页都有一段可以在线运行的示例代码**；
- 示例用「＋ 添加到工作区」放进右侧沙盒，点「运行」即可查看真实结果；
- 右侧「数据库」抽屉随时看数据变化，每次运行都能看到 ts-grm 生成的 SQL 追踪；
- **无需注册登录**——数据库跑在你自己的浏览器里（PGlite，WASM 版 PostgreSQL），数据不离开本机。

## 你会学到什么

教程分三块递进：

1. **概念**：模型、视图（View）、查询 DSL、类型系统——ts-grm 怎么想问题（它没有实体对象，查询直接得到 DTO）；
2. **查询**：条件、排序、取形、分页、聚合、子查询——功能大头；
3. **后端**：驱动、事务、方言、命名策略——部署与深度使用。

「变更 API（保存 / Input DTO）」正在按上游实现进度跟进：上游运行时尚未发布的部分，教程以设计预览呈现并标注适配版本，不会写成已可用的假象。

## 章节地图

| 章节 | 内容 |
|---|---|
| [快速上手](/docs/getting-started/install) | 安装、模型、视图、查询 |
| [核心概念](/docs/core-concepts/model) | 模型、属性、关联、继承多态、DTO 哲学 |
| [查询 API](/docs/query/root-query) | 条件、排序、取形、分页、聚合、子查询、CTE |
| ~~变更 API（save）~~ | Input DTO 保存、根模式、解绑 —— **尚未发布**，随上游 `@ts-grm/core` 实现后开放 |
| [SQL 后端](/docs/sql-backend/driver) | 驱动、事务、方言、命名策略、日志 |
| [API 参考](/docs/reference/core) | core / sql 快速参考 |

正式阅读前，请先看本组第二页「沙盒环境」——了解每页示例在哪里运行、数据库抽屉与数据重置是怎么回事。

## 三条阅读路径

**新用户**（对 ts-grm / 类型级 ORM 都陌生）

按顺序读：快速上手四步 → 核心概念（重点是「DTO 哲学」——与常见 ORM 最大的理念差异）→ 查询前五节，之后按需补。

**ORM 老手**（用过 Prisma / Sequelize / Jimmer）

快速上手快速过 API 手感 → 「DTO 哲学」与「取形进阶」——理念摩擦最大的两处 → 其余按工作场景查。

**深入研究者**（性能、类型系统、方言）

先读 SQL 后端与 API 参考；每个查询页的 SQL 追踪片段直接到沙盒复核。

## 术语速记

| 术语 | 含义 |
|---|---|
| GRM（ORM+） | 对 ORM 的扩展：读写、取形、关联、多态、复合值、公式等完整数据访问能力 |
| 模型（Model） | `model(...)` 声明的实体形状，仅元数据 |
| 视图（View） | `dto.view` 声明的查询结果形状 |
| 取形 | 按视图选择要返回的字段与关联 |
| 列表达式 | 表对象上某列的类型级对象（`book.price`），比较方法在它上面 |
| DTO | 查询 / 保存的载荷形状，没有实体对象 |
| 沙盒 | 本教程在线可运行环境：浏览器本地数据库 + 代码工作区（无需登录） |

## 与上游版本的关系

本教程按 `@ts-grm/core` / `@ts-grm/sql` 的 **0.0.x** 版本适配，每页 frontmatter 标注 `verified` 已校验版本。上游发版活跃，教程会持续跟进。