第10章 调试、排错与文档生成

内容摘要测试通过了，但上线后还是会报错——日志看不懂、慢SQL不知道怎么查、文档没人愿意写。这一章帮你建立一套高效的排错流程：从启动报错到运行时性能瓶颈，都让AI参与分析。还会用Trae这类工具演示“让AI直接跑命令并修正”的动态调试能力。最后给出一个调试沟通模板，确保你给AI提供的最小复现信息足够定位问题。本章实操有两个：一是修复典型的N+1查询问题，二是一键生成项目文档（数据库字典、API文档、README）。

10.1 错误日志高效分析

遇到报错时，不要只看最后一行。把完整日志（前20行+后20行）贴给AI，同时附上相关代码片段。

10.1.1 Spring Boot启动报错

常见启动错误：端口被占用、数据库连不上、Bean循环依赖、配置属性缺失。

示例：报错 Failed to bind properties under 'spring.datasource.password' to java.lang.String。你把完整堆栈发给AI，它很快会定位到application.yml中缩进错误或特殊字符未转义。

让AI帮你分析时，可以这样提问：

“以下Spring Boot启动报错，端口8080已被占用。除了杀死进程，还有没有更优雅的解决办法？请给出三种方案。”

AI会建议：修改server.port、使用随机端口0、或配置环境变量SERVER_PORT。它不会只给一个答案。

10.1.2 Vite编译错误

前端构建失败，常见于路径别名未配置、TypeScript类型错误、依赖版本冲突。把npm run build的完整输出贴给AI，它常常能指出是哪个包的ES模块兼容性问题，并给出vite.config.ts中的optimizeDeps配置。

10.1.3 数据库报错

比如DataIntegrityViolationException: Duplicate entry。AI会提示你检查唯一索引和代码中的并发控制。你可以要求它生成一个幂等的插入逻辑。

关键原则：提供报错时，同时说明你做了什么操作、使用了哪些参数值。AI不需要整个代码仓库，但需要相关的那几行代码。

10.2 性能排查

性能问题通常表现为“接口慢”或“页面加载慢”。让AI参与分析，但最终定位要靠工具。

10.2.1 慢SQL定位与优化

开启Hibernate的SQL日志（spring.jpa.show-sql=true），并加上参数绑定日志（logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE）。拿到一条慢SQL后，发给AI：

“这条SQL执行了3秒，表有10万行数据，请分析原因并给出优化建议。”AI会检查是否有SELECT *、缺失索引、隐式类型转换、OR条件导致索引失效等。

然后让它生成索引DDL：

“为以下查询字段创建索引：where user_id = ? and status in (?, ?)，请写出MySQL索引语句。”

AI会推荐CREATE INDEX idx_user_status ON table(user_id, status)，并解释为什么要按这个顺序。

10.2.2 前端加载慢分析

使用Chrome DevTools的Network和Performance面板。把耗时长的请求或资源列表截图（文字描述）给AI，它会建议：开启gzip、拆分chunk、路由懒加载、图片懒加载。

针对Vue项目，AI可以帮你检查是否存在不必要的组件重复渲染。你可以把一段有性能问题的模板代码发给它，它会指出v-for上没有key、计算属性依赖了响应式对象导致频繁计算等问题。

10.2.3 Vue组件渲染瓶颈排查

提供一个慢速组件，让AI审查：

“这个表格组件渲染1000行需要2秒，如何优化？”

AI会建议：虚拟滚动（el-table-v2）、分页、将子组件拆分为异步组件、使用shallowRef避免深度响应式。并给出具体代码示例。

10.3 技术文档自动生成

AI非常擅长把代码和注释转化为文档。你可以一次性生成以下内容。

10.3.1 Markdown API文档

让AI遍历你的Controller，生成API文档。提示词：

“扫描以下Controller类，生成Markdown格式的API文档，包含端点、方法、请求参数、响应示例。不要添加额外解释。”

AI会输出类似：

## POST /api/courses- 描述：创建课程- 请求体：```json{  "name": "string",  "description": "string",  "maxStudents": 30}

• • 响应：

{  "code": 200,  "data": { "id": 1, ... }}

你也可以让它根据OpenAPI YAML生成更规范的文档。### 10.3.2 数据库字典连接数据库（或扫描实体类），让AI生成数据字典表格：> “根据以下实体类（User, Course, Reservation）生成数据库字典，包含字段名、类型、是否可空、注释。”AI会输出Markdown表格，列名清晰。如果你使用Liquibase或Flyway，它还可以生成变更日志。### 10.3.3 项目README让AI根据项目结构生成README模板：> “为这个Spring Boot + Vue 3项目生成README.md，包含：项目简介、技术栈、快速启动步骤、环境变量说明、API文档链接。”AI会输出一个完整的README框架，你只需补充具体的端口号和环境变量值。### 10.3.4 变更日志根据Git提交记录（可以截取`git log --oneline`）让AI生成CHANGELOG：> “以下是我的Git提交记录，请按语义化版本规范生成CHANGELOG.md，分组为Added、Changed、Fixed。”AI会自动归类，甚至帮你推测版本号。---## 10.4 Trae动态调试能力Trae是一个能直接运行命令并自动修正代码的AI工具。如果你还没有用过，这一节介绍它的典型用法。### 10.4.1 让AI直接运行命令并修正在Trae中，你可以说：  > “运行`npm run build`，如果失败就自动修复。”Trae会执行命令，捕获错误，然后根据错误信息修改代码（如补充缺失的依赖、修复语法），再次运行直到成功。这比手动复制粘贴错误信息效率高得多。类似地，后端场景：  > “启动Spring Boot应用，如果端口被占用就改为8081。”Trae能修改`application.yml`并重启进程。**注意**：这种能力必须你在安全的沙箱环境使用，不要在生产服务器上开启自动修正。### 10.4.2 调试对话最佳模板即使没有Trae，你也可以用普通AI模拟类似的迭代调试。模板如下：

【任务】让Spring Boot应用启动成功。【当前状态】启动报错：HikariPool-1 - Exception during pool initialization.【已尝试】确认MySQL已启动，密码正确。【请AI】分析原因，并给出修改步骤。

AI会建议检查：URL中的时区参数、MySQL驱动版本、是否创建了数据库。每步执行后反馈结果，AI再修正。这种“执行-反馈-修正”循环比一次性生成代码更有效。---## 10.5 调试沟通模板：最小复现信息提供当你需要向AI求助一个bug时，提供以下信息可以提高解决率。你可以把这个模板保存下来。```markdown## 问题描述[一句话描述现象]## 环境信息- 操作系统：- 后端版本/前端Node版本：- 数据库类型及版本：## 复现步骤1. 2. 3. ## 预期行为[应该发生什么]## 实际行为[实际发生了什么，附上错误日志全文或截图文字]## 相关代码（最小化）```[语言][只贴相关的类或方法，不要整个项目]

已尝试过的解决方式

[列出你试过的方案]

使用这个模板后，AI的第一次回答准确率会明显提高。---## 10.6 本章实操：N+1查询修复与一键生成项目文档### 实操1：N+1查询修复**背景**：你的课程管理模块中，`GET /api/courses` 返回课程列表，但每个课程都附带教师信息。你发现日志中执行了1次查询课程 + N次查询教师。**任务**：1. 用AI分析N+1查询原因（例如`Course`实体中`@ManyToOne(fetch = FetchType.LAZY)`，序列化时触发额外查询）。2. 让AI给出两种解决方案：`@EntityGraph(attributePaths = "teacher")` 和 DTO投影。3. 任选一种修改Repository和Service，验证SQL数量降为1次。**验收**：开启`show-sql`，请求课程列表后控制台只输出一条SQL（带JOIN）。### 实操2：一键生成项目文档**任务**：基于你已经完成的会议预定系统或课程管理系统，生成以下三份文档：- API文档（Markdown）- 数据库字典（Markdown表格）- README.md**步骤**：1. 收集所有Controller类代码（或Swagger JSON）和实体类代码。2. 把代码分段发给AI，按10.3节的提示词生成对应文档。3. 将生成的内容整理到项目根目录的`docs/`文件夹下。4. 在README中添加“文档”章节，链接到这些文件。**验收**：一个新加入项目的开发者，只看这些文档就能知道如何启动项目、有哪些接口、数据库表结构是什么。**扩展**：如果你使用GitHub Actions，可以让AI写一个CI脚本，每次推送时自动调用AI生成最新文档并提交到仓库。但这一步非必需。---完成本章，你已经具备独立排查绝大多数开发和运行时问题的能力。下一章是全书最后一个综合实战——我们会把前面所有知识点串起来，做三个完整项目（在线测评系统、知识库系统、考勤请假系统），并讨论团队协作和AI安全红线。最后你会得到一个可放进简历的全栈项目集合。---*本章的Trae调试功能基于该工具2025年的版本，不同版本行为可能有差异。动态调试建议在非生产环境试用。*