@fastcar/cli 0.1.1 → 0.1.3

package/skills/fastcar-database/SKILL.md

@@ -5,7 +5,7 @@ description: FastCar 数据库与缓存开发指南。Use when working with Fast
 
 # FastCar Database
 
-FastCar 数据库模块提供基于装饰器的 ORM 支持，涵盖 MySQL、PostgreSQL、MongoDB 和 Redis，并支持通过 `mysql-tool` 逆向生成 Model 和 Mapper。
+FastCar 数据库模块提供基于装饰器的 ORM 支持，涵盖 MySQL、PostgreSQL、MongoDB 和 Redis。
 
 ## 模块速查
 
@@ -26,10 +26,10 @@ export default new APP();
 #### 定义实体模型
 
 ```typescript
-import { Table, Field, DBType, PrimaryKey, NotNull, Size, CustomType } from "@fastcar/core/annotation";
+import { Table, Field, DBType, PrimaryKey, NotNull, Size } from "@fastcar/core/annotation";
 
-@Table("users")
-class User {
+@Table("entities")
+class Entity {
   @Field("id")
   @DBType("int")
   @PrimaryKey
@@ -41,13 +41,16 @@ class User {
   @Size({ maxSize: 50 })
   name!: string;
 
-  @Field("profile")
+  @Field("data")
   @DBType("json")
-  @CustomType("json")
-  profile: any;
+  data!: any;
 
-  constructor(...args: any) {
-    Object.assign(this, ...args);
+  @Field("created_at")
+  @DBType("datetime")
+  createdAt!: Date;
+
+  constructor(args?: Partial<Entity>) {
+    if (args) Object.assign(this, args);
   }
 }
 ```
@@ -57,206 +60,315 @@ class User {
 ```typescript
 import { Entity, Repository } from "@fastcar/core/annotation";
 import { MysqlMapper } from "@fastcar/mysql";
-import User from "./User";
+import Entity from "./Entity";
 
-@Entity(User)
+@Entity(Entity)
 @Repository
-class UserMapper extends MysqlMapper<User> {}
-
-export default UserMapper;
+class EntityMapper extends MysqlMapper<Entity> {}
+export default EntityMapper;
 ```
 
-#### Service 中使用
+#### MysqlMapper 核心 API
 
 ```typescript
 import { Service, Autowired } from "@fastcar/core/annotation";
-import { OrderEnum } from "@fastcar/core/db";
-import UserMapper from "./UserMapper";
-import User from "./User";
+import { OrderEnum, OperatorEnum } from "@fastcar/core/db";
+import EntityMapper from "./EntityMapper";
+import Entity from "./Entity";
 
 @Service
-class UserService {
+class EntityService {
   @Autowired
-  private userMapper!: UserMapper;
-
-  // 查询单条
-  async getUser(id: number) {
-    return this.userMapper.selectOne({ where: { id } });
-  }
-
-  // 条件查询
-  async queryUsers(name: string) {
-    return this.userMapper.select({
-      where: {
-        name: { value: name },
-        createdAt: { ">=": "2024-01-01", "<=": "2024-12-31" },
-      },
-      orders: { createdAt: OrderEnum.desc },
-      limit: 10,
+  private mapper!: EntityMapper;
+
+  // ===== 查询方法 =====
+  
+  // 查询列表
+  async list() {
+    return this.mapper.select({});
+  }
+
+  // 查询单个
+  async getOne(id: number) {
+    return this.mapper.selectOne({ where: { id } });
+  }
+
+  // 根据主键查询
+  async getByPK(id: number) {
+    return this.mapper.selectByPrimaryKey({ id } as Entity);
+  }
+
+  // 统计记录数
+  async count() {
+    return this.mapper.count({ status: 1 });
+  }
+
+  // 判断是否存在
+  async exists(name: string) {
+    return this.mapper.exist({ name });
+  }
+
+  // ===== 条件查询 =====
+
+  // 简单等于条件
+  async queryByStatus(status: number) {
+    return this.mapper.select({ where: { status } });
+  }
+
+  // 多条件 AND
+  async queryByConditions(name: string, status: number) {
+    return this.mapper.select({
+      where: { name, status, delStatus: false }
     });
   }
 
-  // 数组 IN 查询
+  // 比较运算符
+  async queryByRange(min: number, max: number) {
+    return this.mapper.select({
+      where: { value: { [OperatorEnum.gte]: min, [OperatorEnum.lte]: max } }
+    });
+  }
+
+  // IN 查询
   async queryByIds(ids: number[]) {
-    return this.userMapper.select({
-      where: { id: { IN: ids } },
+    return this.mapper.select({
+      where: { id: { [OperatorEnum.in]: ids } }
+    });
+  }
+
+  // IS NULL 查询
+  async queryDeleted() {
+    return this.mapper.select({
+      where: { deletedAt: { [OperatorEnum.isNUll]: true } }
+    });
+  }
+
+  // ===== 排序和分页 =====
+
+  async getOrdered() {
+    return this.mapper.select({
+      where: { status: 1 },
+      orders: { createdAt: OrderEnum.desc }
     });
   }
 
-  // 新增
-  async createUser(name: string) {
-    const user = new User({ name, createdAt: new Date() });
-    return this.userMapper.saveOne(user);
+  async getPaged(page: number, pageSize: number) {
+    return this.mapper.select({
+      orders: { id: OrderEnum.desc },
+      offset: (page - 1) * pageSize,
+      limit: pageSize
+    });
   }
 
-  // 批量新增
-  async createUsers(users: User[]) {
-    return this.userMapper.saveList(users);
+  // ===== 插入方法 =====
+
+  // 插入单条
+  async create(name: string) {
+    const entity = new Entity({ name, createdAt: new Date() });
+    return this.mapper.saveOne(entity);
   }
 
-  // 更新
+  // 批量插入
+  async createBatch(list: Entity[]) {
+    return this.mapper.saveList(list);
+  }
+
+  // 插入或更新
+  async saveOrUpdate(entity: Entity) {
+    return this.mapper.saveORUpdate(entity);
+  }
+
+  // ===== 更新方法 =====
+
+  // 条件更新
   async updateName(id: number, name: string) {
-    return this.userMapper.update({ where: { id }, row: { name } });
+    return this.mapper.update({
+      where: { id },
+      row: { name, updatedAt: new Date() }
+    });
   }
 
-  // 按主键更新
-  async updateById(user: User) {
-    return this.userMapper.updateByPrimaryKey(user);
+  // 更新单条
+  async updateOne(where: any, row: any) {
+    return this.mapper.updateOne({ where, row });
   }
 
-  // 删除
-  async deleteUser(id: number) {
-    return this.userMapper.delete({ where: { id } });
+  // 根据主键更新
+  async updateById(entity: Entity) {
+    return this.mapper.updateByPrimaryKey(entity);
   }
 
-  // 判断存在
-  async exists(name: string) {
-    return this.userMapper.exist({ name });
+  // 软删除
+  async softDelete(id: number) {
+    return this.mapper.update({
+      where: { id },
+      row: { delStatus: true, deletedAt: new Date() }
+    });
   }
 
-  // 统计
-  async count() {
-    return this.userMapper.count({});
+  // ===== 删除方法 =====
+
+  async deleteById(id: number) {
+    return this.mapper.delete({ where: { id } });
   }
 
-  // 执行原生 SQL
-  async executeSql() {
-    return this.userMapper.execute("SELECT * FROM users WHERE id = 1");
+  async deleteOne(where: any) {
+    return this.mapper.deleteOne(where);
   }
 
-  // 左连接查询
-  async leftJoin() {
-    return this.userMapper.selectByCustom({
-      join: [
-        {
-          type: "LEFT",
-          table: "orders o",
-          on: "o.user_id = t.id",
-        },
-      ],
+  // ===== 高级查询 =====
+
+  // selectByCustom 支持 JOIN、分组、聚合
+  async advancedQuery() {
+    // 指定字段 + 泛型类型
+    const results = await this.mapper.selectByCustom<{ 
+      id: number; 
+      name: string; 
+      relatedName: string;
+    }>({
       tableAlias: "t",
+      fields: ["t.id", "t.name", "r.name as relatedName"],
+      join: [{
+        type: "LEFT",
+        table: "related_table r",
+        on: "r.entity_id = t.id"
+      }],
+      where: { "t.status": 1 },
+      camelcaseStyle: true,
     });
-  }
 
-  // 强制索引
-  async forceIndex() {
-    return this.userMapper.select({
-      forceIndex: ["idx_name"],
-      orders: { name: OrderEnum.desc },
-      limit: 1,
+    // 聚合查询
+    const stats = await this.mapper.selectByCustom({
+      fields: [
+        "status",
+        "COUNT(*) as totalCount",
+        "MAX(created_at) as lastCreated"
+      ],
+      groups: ["status"],
+      orders: { totalCount: OrderEnum.desc }
     });
+
+    return { results, stats };
   }
 
-  // 使用函数
-  async formatDate() {
-    return this.userMapper.select({
-      fields: ['DATE_FORMAT(created_at, "%Y-%m-%d %H:%i:%s") as createdAt'],
-    });
+  // 自定义 SQL
+  async customQuery() {
+    return this.mapper.query(
+      "SELECT * FROM entities WHERE status = ? AND created_at > ?",
+      [1, "2024-01-01"]
+    );
   }
 }
 ```
 
-#### 多数据源
+#### 常用查询条件速查表
 
-在 `application.yml` 中配置多个数据源，Service 中通过指定数据源名称切换。
+```typescript
+import { OperatorEnum, OrderEnum } from "@fastcar/core/db";
 
-#### 事务
+// 等于 (默认)
+{ where: { status: 1 } }
 
-使用 `@Transactional`（如果框架提供）或手动通过 `SqlSession` 控制事务边界。
+// 不等于
+{ where: { status: { [OperatorEnum.neq]: 1 } } }
 
-### PostgreSQL (@fastcar/pgsql)
+// 大于 / 大于等于 / 小于 / 小于等于
+{ where: { age: { [OperatorEnum.gt]: 18 } } }
+{ where: { age: { [OperatorEnum.gte]: 18, [OperatorEnum.lte]: 60 } } }
+
+// IN / NOT IN
+{ where: { id: { [OperatorEnum.in]: [1, 2, 3] } } }
+{ where: { id: { [OperatorEnum.notin]: [1, 2, 3] } } }
 
-#### 开启 PostgreSQL
+// IS NULL / IS NOT NULL
+{ where: { deletedAt: { [OperatorEnum.isNUll]: true } } }
+{ where: { deletedAt: { [OperatorEnum.isNotNull]: true } } }
+
+// 排序
+{ orders: { createdAt: OrderEnum.desc } }
+
+// 分页
+{ offset: 0, limit: 10 }
+```
+
+#### 事务处理
 
 ```typescript
-import { Application } from "@fastcar/core/annotation";
-import { EnablePgsql } from "@fastcar/pgsql/annotation";
+import { SqlSession } from "@fastcar/core/annotation";
+import { MysqlDataSourceManager } from "@fastcar/mysql";
 
-@Application
-@EnablePgsql
-class APP {}
-export default new APP();
+@Service
+class BizService {
+  @Autowired
+  private dsm!: MysqlDataSourceManager;
+
+  @Autowired
+  private mapperA!: MapperA;
+
+  @Autowired
+  private mapperB!: MapperB;
+
+  async transactionExample(dataA: any, dataB: any) {
+    const sessionId = await this.dsm.beginTransaction();
+    
+    try {
+      await this.mapperA.saveOne(dataA, undefined, sessionId);
+      await this.mapperB.update({
+        where: { id: dataB.id },
+        row: { status: dataB.status }
+      }, undefined, sessionId);
+      
+      await this.dsm.commit(sessionId);
+      return true;
+    } catch (error) {
+      await this.dsm.rollback(sessionId);
+      throw error;
+    }
+  }
+}
 ```
 
-#### 定义 Mapper
+### PostgreSQL (@fastcar/pgsql)
 
 ```typescript
-import { Entity, Repository } from "@fastcar/core/annotation";
+import { EnablePgsql } from "@fastcar/pgsql/annotation";
 import { PgsqlMapper } from "@fastcar/pgsql";
-import User from "./User";
 
-@Entity(User)
+@Application
+@EnablePgsql
+class APP {}
+
+@Entity(Entity)
 @Repository
-class UserMapper extends PgsqlMapper<User> {}
+class EntityMapper extends PgsqlMapper<Entity> {}
 ```
 
-用法与 `MysqlMapper` 基本一致，支持相同的查询条件和 CRUD 操作。
+用法与 `MysqlMapper` 基本一致。
 
 ### MongoDB (@fastcar/mongo)
 
-#### 开启 MongoDB
-
 ```typescript
-import { Application } from "@fastcar/core/annotation";
 import { EnableMongo } from "@fastcar/mongo/annotation";
+import { MongoMapper } from "@fastcar/mongo";
 
 @Application
 @EnableMongo
 class APP {}
-export default new APP();
-```
 
-#### 定义 Mapper
-
-```typescript
-import { Entity, Repository } from "@fastcar/core/annotation";
-import { MongoMapper } from "@fastcar/mongo";
-import User from "./User";
-
-@Entity(User)
+@Entity(Entity)
 @Repository
-class UserMapper extends MongoMapper<User> {}
+class EntityMapper extends MongoMapper<Entity> {}
 ```
 
 ### Redis (@fastcar/redis)
 
-#### 开启 Redis
-
 ```typescript
-import { Application } from "@fastcar/core/annotation";
 import { EnableRedis } from "@fastcar/redis/annotation";
+import { RedisClient } from "@fastcar/redis/annotation";
 
 @Application
 @EnableRedis
 class APP {}
-export default new APP();
-```
-
-#### 使用 RedisTemplate
-
-```typescript
-import { Service, Autowired } from "@fastcar/core/annotation";
-import { RedisClient } from "@fastcar/redis/annotation";
 
 @Service
 class CacheService {
@@ -274,22 +386,42 @@ class CacheService {
   async del(key: string) {
     await this.redis.del(key);
   }
+
+  // Hash 操作
+  async hset(key: string, field: string, value: string) {
+    await this.redis.hset(key, field, value);
+  }
+
+  async hget(key: string, field: string) {
+    return this.redis.hget(key, field);
+  }
+
+  // List 操作
+  async lpush(key: string, value: string) {
+    await this.redis.lpush(key, value);
+  }
+
+  async rpop(key: string) {
+    return this.redis.rpop(key);
+  }
 }
 ```
 
 ## 数据库逆向生成 (@fastcar/mysql-tool)
 
-### 生成配置文件
-
 ```bash
+# 生成配置文件
 fastcar-cli reverse:init
+
+# 执行逆向生成
+fastcar-cli reverse
 ```
 
-### 配置文件示例
+配置文件示例：
 
 ```json
 {
-  "tables": ["users", "orders"],
+  "tables": ["table1", "table2"],
   "modelDir": "D:/project/src/model",
   "mapperDir": "D:/project/src/mapper",
   "dbConfig": {
@@ -298,25 +430,10 @@ fastcar-cli reverse:init
     "user": "root",
     "password": "password",
     "database": "test_db"
-  },
-  "style": {
-    "tabWidth": 4,
-    "printWidth": 200,
-    "trailingComma": "es5",
-    "useTabs": true,
-    "parser": "typescript",
-    "endOfLine": "crlf"
-  },
-  "ignoreCamelcase": false
+  }
 }
 ```
 
-### 执行逆向生成
-
-```bash
-fastcar-cli reverse
-```
-
 ## application.yml 数据库配置
 
 ```yaml
@@ -329,6 +446,7 @@ mysql:
   database: mydb
   username: root
   password: password
+  connectionLimit: 10
 
 pgsql:
   host: localhost
@@ -372,3 +490,118 @@ npm i @fastcar/core @fastcar/mysql @fastcar/redis
 # 4. 启动应用
 npm run debug
 ```
+
+## 注意事项
+
+1. **排序必须使用 OrderEnum**：`orders: { createdAt: OrderEnum.desc }`，不能使用字符串 `"DESC"`
+2. **主键查询**：`selectByPrimaryKey` 和 `updateByPrimaryKey` 需要传入包含主键字段的对象
+3. **批量插入**：`saveList` 会自动分批处理（每批1000条）
+4. **软删除**：建议使用 `update` 方法更新 `delStatus` 字段，而不是物理删除
+
+## 编码规范
+
+### 1. 实体对象创建规范
+
+```typescript
+// ✅ 正确：使用 key-value 形式创建对象
+const entity = new Entity({
+    name: "示例",
+    status: 1,
+    createTime: new Date(),
+});
+
+// ❌ 错误：逐行赋值创建对象
+const entity = new Entity();
+entity.name = "示例";
+entity.status = 1;
+```
+
+### 2. 分页查询规范
+
+```typescript
+// ✅ 正确：使用 SQL limit/offset 分页
+const total = await this.mapper.count(where);
+const list = await this.mapper.select({
+    where: where,
+    orders: { createTime: OrderEnum.desc },
+    offset: (page - 1) * pageSize,
+    limit: pageSize,
+});
+
+// ❌ 错误：先全表查询再用 JS slice 分页
+const list = await this.mapper.select({ where });
+const pageData = list.slice((page - 1) * pageSize, page * pageSize);
+```
+
+### 3. 查询条件规范
+
+```typescript
+import { OperatorEnum } from "@fastcar/core/db";
+
+// ✅ 正确：使用 OperatorEnum
+const list = await this.mapper.select({
+    where: {
+        age: { [OperatorEnum.gte]: 18, [OperatorEnum.lte]: 60 },
+        status: { [OperatorEnum.in]: [1, 2, 3] },
+    },
+});
+```
+
+### 4. 接口返回规范
+
+```typescript
+// ✅ 正确：返回空数据
+if (records.length === 0) {
+    return Result.ok({ list: [], total: 0 });
+}
+
+// ❌ 错误：返回模拟数据
+if (records.length === 0) {
+    return Result.ok({ list: [{ name: "模拟数据1" }] });
+}
+```
+
+### 5. 更新操作规范
+
+```typescript
+// ✅ 正确：更新少于3个字段时使用 update/updateOne
+await this.mapper.updateOne({
+    where: { id },
+    row: { lastLoginTime: new Date() },
+});
+
+// ❌ 错误：为了更新1-2个字段而查询整个实体对象
+const entity = await this.mapper.selectByPrimaryKey({ id });
+entity.lastLoginTime = new Date();
+await this.mapper.updateByPrimaryKey(entity);
+```
+
+### 6. 复杂查询优化
+
+```typescript
+// ✅ 正确：使用 selectByCustom + JOIN 一条 SQL 完成
+interface QueryResult {
+    id: number;
+    name: string;
+    relatedName: string;
+}
+
+const results = await this.mapper.selectByCustom<QueryResult>({
+    tableAlias: "t",
+    fields: ["t.id", "t.name", "r.name as relatedName"],
+    join: [{
+        type: "INNER",
+        table: "related_table r",
+        on: "r.entity_id = t.id",
+    }],
+    where: { "t.status": 1 },
+    camelcaseStyle: true,
+});
+
+// ❌ 错误：多次查询 + 内存组装（N+1 问题）
+const list = await this.mapper.select({});
+for (const item of list) {
+    const related = await this.relatedMapper.selectOne({ ... });
+    // 内存组装...
+}
+```