AI 工具配置指南

让 AI 助手成为你的 DLZ-DB 开发伙伴

概述

DLZ-DB 专门为 AI 辅助开发做了优化设计：

入口收敛：所有操作从 DB. 开始，决策树浅
规则统一：条件方法、返回值都有机械规则
文档精简：核心使用规范可压缩到 1000 token 以内
调用栈清晰：异常信息直接定位到业务代码行

本文档将指导你在主流 AI 工具中配置 DLZ-DB 的上下文，让 AI 助手能够：

正确生成 DLZ-DB 代码
理解项目约定和最佳实践
快速定位和修复问题
提供符合项目规范的建议

一、Cursor 配置

1.1 项目级配置（推荐）

在项目根目录创建 .cursorrules 文件：

# DLZ-DB 项目规范

## 数据库操作规范

本项目使用 DLZ-DB 框架进行数据库操作，遵循以下规范：

### 核心入口

- `DB.Pojo` - 有 Bean 的 CRUD（首选）
- `DB.Table` - 动态表名场景
- `DB.Jdbc` - 简单 SQL，使用 ? 占位符
- `DB.Sql` - 预设/复杂 SQL，使用 #{key} 占位符
- `DB.Tx` - 编程式事务
- `DB.Batch` - 批量操作
- `DB.Dynamic` - 数据源切换

### 条件构造

所有条件方法支持三参形式：`eq(boolean condition, field, value)`
- condition 为 false 时自动跳过该条件
- field 使用 Lambda 方法引用：`User::getName`
- 嵌套条件：`or(o -> ...)` / `and(a -> ...)`

### 返回值规则

- `queryBean()` → 单个 Bean
- `queryBeanList()` → List&lt;Bean>
- `queryBeanPage()` → Page&lt;Bean>
- `queryOne()` → ResultMap（单行）
- `queryList()` → List&lt;ResultMap>
- `queryOne(Class)` → 指定类型
- 写操作必须以 `.execute()` 结尾

### 硬约束

1. 无 Mapper/DAO/Wrapper 类，直接使用 `DB.Pojo.*`
2. 占位符不混用：`DB.Jdbc` 用 `?`；`DB.Sql` 用 `#{key}`
3. 查询列用 `columns()` 不是 `select()`
4. LIKE 用 `like()` / `likeLeft()` / `likeRight()` / `notLike()`
5. 插入返回自增主键：`.insertWithAutoKey()` 不是 `.execute()`
6. 物理删除/查询绕过逻辑删除：`.ignoreLogicDelete(true)`
7. `in()` 不可传单值，必须传 List、CSV 字符串或 "sql:子查询"
8. 批量操作用 `DB.Batch.insert(users)`，不是 `insertBatch()`

### Entity 约定

- 表名：驼峰转下划线（`User.class` → `user`）
- 自定义表名：`@TableName("t_user")`
- 字段映射：`User::getUserName` → `user_name`
- 自定义字段：`@TableField("email_address")`
- 主键标识：`@TableId`
- 逻辑删除：Bean 含 `isDeleted` 字段自动启用

### 代码示例

// 查询
User user = DB.Pojo.select(User.class)
    .eq(User::getId, 1)
    .queryBean();

List&lt;User> users = DB.Pojo.select(User.class)
    .eq(User::getStatus, 1)
    .like(User::getName, "张")
    .queryBeanList();

// 分页
Page&lt;User> page = DB.Pojo.select(User.class)
    .eq(User::getStatus, 1)
    .page(1, 10)
    .queryBeanPage();

// 插入
DB.Pojo.insert(user);
Long id = DB.Pojo.insert(user).insertWithAutoKey();

// 更新
DB.Pojo.update(User.class)
    .set(User::getName, "新名字")
    .eq(User::getId, id)
    .execute();

// 删除
DB.Pojo.delete(User.class)
    .eq(User::getId, id)
    .execute();

// 批量
DB.Batch.insert(users);

// 事务
DB.Tx.run(() -> {
    DB.Pojo.insert(order);
    DB.Pojo.insert(orderItem);
});

// 多数据源
DB.Dynamic.use("slave", () -> 
    DB.Pojo.select(User.class).queryBeanList()
);

完整文档

参考项目中的 docs/第05章-AI辅助/5.1-AI速读.md 获取完整规范。

### 1.2 使用方式

配置完成后，Cursor 会自动将规则应用到所有对话中：

1. **代码生成**：直接描述需求，AI 会生成符合规范的代码

你：创建一个查询用户列表的接口，支持按状态和名称筛选 AI：[生成符合 DLZ-DB 规范的代码]


2. **代码审查**：选中代码后按 `Cmd/Ctrl + K`，输入 "review"

AI 会检查：

是否使用了正确的入口
占位符是否正确
返回值处理是否规范

3. **问题修复**：遇到错误时，AI 会根据规范提供解决方案

### 1.3 高级技巧

**引用特定文档**：

@docs/第05章-AI辅助/5.1-AI速读.md 帮我生成一个复杂查询


**临时覆盖规则**：

忽略 .cursorrules，这次我需要使用原生 JDBC

---

## 二、GitHub Copilot 配置

### 2.1 工作区配置

在项目根目录创建 `.github/copilot-instructions.md`：

```markdown
# DLZ-DB 代码生成指南

## 数据库操作

使用 DLZ-DB 框架，入口为 `DB.Pojo`、`DB.Table`、`DB.Jdbc`、`DB.Sql`。

### 查询模板

```java
// 单条查询
User user = DB.Pojo.select(User.class)
    .eq(User::getId, id)
    .queryBean();

// 列表查询
List&lt;User> users = DB.Pojo.select(User.class)
    .eq(status != null, User::getStatus, status)
    .like(name != null, User::getName, name)
    .queryBeanList();

// 分页查询
Page&lt;User> page = DB.Pojo.select(User.class)
    .page(pageNum, pageSize)
    .queryBeanPage();

写操作模板

// 插入
DB.Pojo.insert(user);

// 更新
DB.Pojo.update(User.class)
    .set(User::getName, newName)
    .eq(User::getId, id)
    .execute();

// 删除
DB.Pojo.delete(User.class)
    .eq(User::getId, id)
    .execute();

关键约束

条件字段使用 Lambda：User::getName
写操作必须 .execute() 结尾
in() 不能传单值
查询列用 columns() 不是 select()

### 2.2 使用方式

1. **行内补全**：输入注释，Copilot 自动生成代码
   ```java
   // 查询状态为1的用户列表，按创建时间倒序
   // [Copilot 会生成符合规范的代码]

Chat 对话：在 Copilot Chat 中提问

你：如何实现用户分页查询？
Copilot：[根据配置生成 DLZ-DB 代码]

代码解释：选中代码，右键 → Copilot → Explain
```
Copilot 会解释代码并指出是否符合 DLZ-DB 规范
```

三、JetBrains AI Assistant 配置

3.1 项目上下文配置

在 IntelliJ IDEA / WebStorm 中：

打开 Settings → Tools → AI Assistant
在 Project Context 中添加：

项目使用 DLZ-DB 数据库框架。

核心规则：
- 入口：DB.Pojo（有Bean）、DB.Table（动态表名）、DB.Jdbc（简单SQL）
- 条件：eq(User::getId, 1)，使用 Lambda 方法引用
- 返回：queryBean()、queryBeanList()、queryBeanPage()
- 写操作：必须 .execute() 结尾
- 占位符：DB.Jdbc 用 ?，DB.Sql 用 #{key}
- 批量：DB.Batch.insert(list)
- 事务：DB.Tx.run(() -> {...})

参考文档：docs/第05章-AI辅助/5.1-AI速读.md

3.2 自定义 Prompt

创建常用 Prompt 模板：

模板 1：生成 CRUD

根据 Entity 类 {ClassName} 生成标准 CRUD 方法，使用 DLZ-DB 框架：
- 单条查询（按 ID）
- 列表查询（支持条件筛选）
- 分页查询
- 插入
- 更新
- 删除

模板 2：生成复杂查询

使用 DLZ-DB 生成查询方法：
- 表：{TableName}
- 条件：{Conditions}
- 排序：{OrderBy}
- 是否分页：{Yes/No}

3.3 使用方式

快速生成：Alt + Enter → AI Actions → Generate with AI
代码审查：选中代码 → Ctrl + Shift + A → "AI: Review Code"
重构建议：右键 → AI Assistant → Suggest Refactoring

四、Windsurf 配置

4.1 项目配置文件

在项目根目录创建 windsurf.config.json：

{
  "ai": {
    "context": {
      "framework": "DLZ-DB",
      "rules": [
        "使用 DB.Pojo 进行 Bean 操作",
        "条件字段使用 Lambda 方法引用",
        "写操作必须以 .execute() 结尾",
        "in() 方法不能传单值",
        "批量操作使用 DB.Batch",
        "事务使用 DB.Tx.run()"
      ],
      "references": [
        "docs/第05章-AI辅助/5.1-AI速读.md"
      ]
    },
    "codeTemplates": {
      "query": "DB.Pojo.select({Entity}.class).eq({Entity}::{Field}, {Value}).queryBean()",
      "queryList": "DB.Pojo.select({Entity}.class).queryBeanList()",
      "insert": "DB.Pojo.insert({entity})",
      "update": "DB.Pojo.update({Entity}.class).set({Entity}::{Field}, {Value}).eq({Entity}::getId, {id}).execute()",
      "delete": "DB.Pojo.delete({Entity}.class).eq({Entity}::getId, {id}).execute()"
    }
  }
}

4.2 使用方式

智能补全：输入 DB. 后，Windsurf 会根据上下文提示
模板生成：输入 /template query User 生成查询代码
文档查询：输入 /docs DLZ-DB 分页 查询相关文档

五、Claude / ChatGPT 配置

5.1 会话初始化 Prompt

每次新会话开始时，先发送以下 Prompt：

我正在使用 DLZ-DB 数据库框架开发 Java 项目。请遵循以下规范生成代码：

## 核心入口
- DB.Pojo - 有 Bean 的 CRUD（首选）
- DB.Table - 动态表名
- DB.Jdbc - 简单 SQL，? 占位符
- DB.Sql - 预设 SQL，#{key} 占位符

## 条件构造
- 使用 Lambda 方法引用：User::getName
- 三参形式：eq(condition, field, value)
- 嵌套：or(o -> ...) / and(a -> ...)

## 返回值
- queryBean() → 单个 Bean
- queryBeanList() → List&lt;Bean>
- queryBeanPage() → Page&lt;Bean>
- queryOne() → ResultMap
- 写操作必须 .execute() 结尾

## 硬约束
1. 无 Mapper/DAO，直接 DB.Pojo.*
2. 占位符不混用
3. 查询列用 columns() 不是 select()
4. in() 不能传单值
5. 批量用 DB.Batch.insert(list)

## 示例
```java
// 查询
User user = DB.Pojo.select(User.class).eq(User::getId, 1).queryBean();

// 插入
DB.Pojo.insert(user);

// 更新
DB.Pojo.update(User.class).set(User::getName, "新名字").eq(User::getId, id).execute();

// 删除
DB.Pojo.delete(User.class).eq(User::getId, id).execute();

// 事务
DB.Tx.run(() -> { ... });

请确认你理解了这些规范。

### 5.2 使用技巧

**1. 上传参考文档**

将 `docs/第05章-AI辅助/5.1-AI速读.md` 上传到对话中：

我上传了 DLZ-DB 的 AI 速读文档，请基于这个文档帮我生成代码

**2. 分步骤提问**

第一步：帮我设计 User 实体类第二步：生成 User 的 CRUD 方法第三步：添加复杂查询方法

**3. 代码审查**

请审查以下代码是否符合 DLZ-DB 规范： [粘贴代码]

---

## 六、效果对比

### 6.1 未配置 AI 辅助

**用户提问**：

帮我写一个查询用户的方法

**AI 回答**（可能使用 MyBatis 风格）：
```java
@Mapper
public interface UserMapper {
    @Select("SELECT * FROM user WHERE id = #{id}")
    User selectById(Long id);
}

6.2 配置 AI 辅助后

用户提问：

帮我写一个查询用户的方法

AI 回答（使用 DLZ-DB 规范）：

public User getUserById(Long id) {
    return DB.Pojo.select(User.class)
        .eq(User::getId, id)
        .queryBean();
}

七、核心优势

7.1 提高开发效率

减少沟通成本：AI 直接生成符合项目规范的代码
降低学习曲线：新成员通过 AI 快速掌握框架用法
统一代码风格：所有 AI 生成的代码风格一致

7.2 提升代码质量

避免常见错误：AI 会遵循硬约束，避免占位符混用等问题
最佳实践：AI 生成的代码符合框架最佳实践
即时反馈：代码审查时 AI 会指出不规范之处

7.3 加速问题解决

精准定位：AI 理解框架特性，能快速定位问题
上下文感知：AI 知道项目使用的框架和约定
文档查询：AI 可以快速引用相关文档

八、最佳实践

8.1 配置建议

优先使用项目级配置：确保团队成员使用相同的 AI 规则
定期更新规则：框架升级后及时更新 AI 配置
保持规则精简：只包含核心规则，避免信息过载

8.2 使用建议

明确需求：向 AI 描述清晰的需求，包括表名、字段、条件等
分步骤进行：复杂功能分解为多个小步骤
验证结果：AI 生成的代码需要人工审查
反馈优化：发现 AI 生成的代码有问题时，及时调整 Prompt

8.3 团队协作

统一配置：团队使用相同的 AI 配置文件
知识共享：分享有效的 Prompt 模板
持续改进：根据实际使用情况优化配置

九、常见问题

Q1：AI 生成的代码不符合规范怎么办？

A：检查以下几点：

配置文件是否正确放置
配置内容是否完整
是否在对话开始时初始化了上下文
尝试更明确地描述需求

Q2：不同 AI 工具的配置可以共用吗？

A：核心规则可以共用，但配置文件格式不同：

Cursor 使用 .cursorrules
Copilot 使用 .github/copilot-instructions.md
Windsurf 使用 windsurf.config.json

建议维护一份核心规则文档，然后转换为不同工具的格式。

Q3：如何让 AI 生成更复杂的查询？

A：提供更详细的上下文：

使用 DLZ-DB 生成查询方法：
- 表：user
- 条件：status=1 AND (name LIKE '%张%' OR address LIKE '%张%')
- 排序：create_time DESC
- 分页：是

Q4：AI 能帮助迁移 MyBatis 代码吗？

A：可以。提供 MyBatis 代码并说明：

请将以下 MyBatis 代码转换为 DLZ-DB 代码：
[粘贴 MyBatis 代码]

十、进阶技巧

10.1 自定义代码片段

在 AI 配置中添加常用代码片段：

// 分页查询模板
public Page&lt;{Entity}> page{Entity}(Integer pageNum, Integer pageSize, {Params}) {
    return DB.Pojo.select({Entity}.class)
        .eq(condition1, {Entity}::{Field1}, {param1})
        .like(condition2, {Entity}::{Field2}, {param2})
        .page(pageNum, pageSize)
        .queryBeanPage();
}

// 批量插入模板
public void batchInsert(List&lt;{Entity}> list) {
    DB.Batch.insert(list);
}

// 事务模板
public void transaction() {
    DB.Tx.run(() -> {
        // 业务逻辑
    });
}

10.2 结合项目文档

将项目特定的约定也加入 AI 配置：

## 项目约定

- 所有 Entity 放在 entity 包下
- Service 层方法命名：get/list/page/save/update/remove
- Controller 返回统一使用 Result&lt;T>
- 分页参数使用 PageRequest

10.3 多数据源场景

## 多数据源配置

项目配置了两个数据源：
- default：主库（读写）
- slave：从库（只读）

查询优先使用从库：
```java
List&lt;User> users = DB.Dynamic.use("slave", () ->
    DB.Pojo.select(User.class).queryBeanList()
);

写操作使用主库（默认）：

DB.Pojo.insert(user);  // 自动使用 default 数据源

---

## 十一、总结

通过合理配置 AI 工具，你可以：

✅ **提高开发效率**：AI 直接生成符合规范的代码  
✅ **降低学习成本**：新成员快速上手 DLZ-DB  
✅ **统一代码风格**：团队代码风格一致  
✅ **减少错误**：AI 遵循框架约束，避免常见问题  
✅ **加速问题解决**：AI 理解框架特性，快速定位问题  

**关键要点**：
1. 选择合适的 AI 工具并正确配置
2. 保持配置文件精简和更新
3. 明确描述需求，分步骤进行
4. 人工审查 AI 生成的代码
5. 团队统一配置，持续优化

---

## 相关文档

- [5.1 AI 速读](./5.1-AI速读.md) - AI 快速参考规范
- [1.3 五分钟上手](../第01章-快速入门/1.3-五分钟上手.md) - 快速入门指南
- [2.3 条件构造器](../第02章-基础操作/2.3-条件构造器.md) - 条件构造详解
- [7.1 最佳实践](../第07章-最佳实践/7.1-最佳实践.md) - 开发最佳实践

---

&lt;div>
<strong>让 AI 成为你的开发伙伴，而不是负担</strong>
&lt;/div>

概述​

一、Cursor 配置​

1.1 项目级配置（推荐）​

完整文档​

写操作模板​

关键约束​

三、JetBrains AI Assistant 配置​

3.1 项目上下文配置​

3.2 自定义 Prompt​

3.3 使用方式​

四、Windsurf 配置​

4.1 项目配置文件​

4.2 使用方式​

五、Claude / ChatGPT 配置​

5.1 会话初始化 Prompt​

6.2 配置 AI 辅助后​

七、核心优势​

7.1 提高开发效率​

7.2 提升代码质量​

7.3 加速问题解决​

八、最佳实践​

8.1 配置建议​

8.2 使用建议​

8.3 团队协作​

九、常见问题​

Q1：AI 生成的代码不符合规范怎么办？​

Q2：不同 AI 工具的配置可以共用吗？​

Q3：如何让 AI 生成更复杂的查询？​

Q4：AI 能帮助迁移 MyBatis 代码吗？​

十、进阶技巧​

10.1 自定义代码片段​

10.2 结合项目文档​

10.3 多数据源场景​

概述