最近在重构公司的 NestJS 微服务模块为了对比不同模型的长上下文生成效果我一直在用 kulaaileadhi.cn这个 AI 模型聚合平台来回切模型测试。今天借此聊聊深度使用 Gemini 3.5 辅助编程的一个实战场景30 分钟内给一个 NestJS 项目生成完整的代码注释。为什么选 Gemini 3.5 做这件事写代码一时爽补文档火葬场。——这大概是每个开发者最真实的写照。高质量的 API 文档和代码注释不仅能拯救交接项目的同事更是团队工程规范的底线。手动注释一个中型 NestJS 项目30 个 Controller Service至少需要 4-6 小时。但 Gemini 3.5 凭借 100 万 token 的上下文窗口可以一次性吃下整个项目的源代码直接基于现有代码风格生成注释。这个能力在代码注释场景下优势明显。Gemini 3.5 Flash 在 Terminal-Bench 编码测试上拿了 76.2%速度 289 tokens/s比 Claude Opus 4.7 和 GPT-5.5 快 4 倍以上。价格 1.50/百万token输入、1.50/百万token输入、9.00/百万 token 输出。对注释这种量大但不需要深度推理的任务Flash 版本的性价比极高。准备工作导出项目上下文在提示词设计之前先把项目的关键信息整理好。第一步导出项目目录树。在终端执行tree src/ --prune -I node_modules得到一个简短的目录结构。第二步合并核心代码文件。把需要注释的 Controller、Service、DTO、Module 文件合并为一个长文本。Gemini 3.5 的上下文窗口能轻松容纳整个中型项目。第三步提供项目拓扑。在 Prompt 中明确告诉它哪些是核心文件、哪些是调用上下文参考。这一步很关键——Gemini 3.5 虽然能装下整个项目但如果直接无脑丢二三十个文件注意力机制会产生大海捞针式的衰减。提示词设计约束优先过滤幻觉提示词怎么写决定注释质量。帮我写注释和为每个 Controller 方法生成符合 NestJS 规范的 JSDoc 注释包含 summary、description、param、returns 标签——两个提示词得到的结果差距非常大。我实测通过率最高的一套提示词模板texttext【角色】你是一个精通 NestJS 和 TypeScript 的高级后端工程师。 【上下文】以下是当前项目的目录结构和核心代码文件 src/ ├── modules/ │ ├── user/ │ │ ├── user.controller.ts (核心待注释文件) │ │ ├── user.service.ts (核心待注释文件) │ │ └── dto/ │ │ └── create-user.dto.ts │ └── order/ │ ├── order.controller.ts │ └── order.service.ts ├── common/ │ └── guards/auth.guard.ts (调用上下文参考) 【任务】请为上述所有 Controller 和 Service 文件中的每个公开方法生成完整的 JSDoc 注释。 【规范】 1. 使用 summary 一行概括方法功能 2. 使用 description 详细说明业务逻辑 3. 使用 param 标注每个参数的类型和含义 4. 使用 returns 标注返回值类型和含义 5. 使用 throws 标注可能抛出的异常 6. 对于使用了装饰器的方法如 UseGuards在注释中说明权限要求 【限制】 - 禁止使用 // 保持不变、// 省略其余代码 等占位符 - 即使是没有修改的方法和类成员也必须完整输出 - 我需要直接复制并替换整个文件 - 注释语言使用英文符合 JSDoc 标准规范这个模板有三个关键设计约束优先。把注释规范写死在提示词里避免模型自由发挥。Gemini 3.5 有时会热心地多写两段解释但注释场景我们只需要结构化的 JSDoc 标签。强制无损输出。Gemini 3.5 特别喜欢在生成长文件时使用// 此处省略其余代码的占位符。在自动化 CI/CD 或直接 Copy 代码时这简直是灾难。所以必须在提示词中明确禁止。文件拓扑引导。明确标注哪些是核心待注释文件、哪些是上下文参考。这样模型的注意力会集中在核心文件上上下文参考文件只用来理解调用关系。实战过程分步生成逐文件校验复杂功能拆成小步骤分步生成比一次性描述所有需求效果好。第一轮Controller 层注释约 10 分钟。把所有 Controller 文件一次性喂给 Gemini 3.5让它只处理 Controller 方法的注释。生成的 JSDoc 注释质量很高——summary 精准概括、param 和 returns 类型标注完整、throws 异常说明到位。第二轮Service 层注释约 10 分钟。同样的方式处理 Service 文件。Service 层的注释需要更多业务逻辑描述Gemini 3.5 在这方面表现不错——它能根据代码中的 Prisma 调用和条件判断推断出业务意图。第三轮DTO 和 Guard 注释约 5 分钟。DTO 文件通常较短一次性生成即可。Guard 文件的注释重点是权限说明Gemini 3.5 能正确识别UseGuards装饰器并说明所需角色。第四轮校验和修正约 5 分钟。逐文件检查生成的注释主要关注三个方面实测效率数据环节手动注释Gemini 3.5 辅助效率提升Controller 层12 个文件~90 分钟~10 分钟~89%Service 层10 个文件~80 分钟~10 分钟~87%DTO Guard8 个文件~30 分钟~5 分钟~83%校验和修正~60 分钟~5 分钟~92%总计~4 小时~30 分钟~87%30 分钟搞定一个中型 NestJS 项目的完整代码注释。三个必须注意的坑第一Gemini 3.5 偶尔会发明不存在的参数。对于复杂的 DTO它有时会根据业务语义推测出代码中未定义的字段。校验时重点检查 param 标注是否和代码中的实际参数一致。第二注释语言风格需要约束。如果不指定注释语言Gemini 3.5 默认用英文但偶尔会在英文注释中夹杂中文说明。建议在系统指令中明确写死语言要求。第三Temperature 要调低。代码注释是确定性任务不需要创意。建议将温度值调低至 0.1 或 0防止模型自己发明注释内容。趋势AI 代码注释正在从可选变成标配两个判断。第一代码注释的自动化程度正在快速提升。从 GitHub Copilot 的实时补全注释到 Compodoc 的自动化文档生成再到 Teable 的代码即文档理念整个行业正在把注释从人力密集型工作变成自动化流水线。Gemini 3.5 的 100 万 token 上下文窗口让一次性注释整个项目成为现实。第二混合使用多个模型是当前务实策略。注释这种量大、结构化、不需要深度推理的任务用 Gemini 3.5 Flash 的性价比最高——速度快、价格低。但如果需要注释复杂的业务逻辑或算法实现可以灵活切换到 Claude 或 GPT-5.5 做局部深度注释。通过聚合平台灵活切换比绑定单一模型更稳妥。拿自己的真实项目跑一遍比看任何评测都靠谱。效率数据基于 2026 年 Q2 实测整理模型能力以最新公告为准。提示词模板参考社区最佳实践。
Gemini 3.5 实战：30 分钟搞定 NestJS 项目的完整代码注释
发布时间：2026/6/9 12:52:30
最近在重构公司的 NestJS 微服务模块为了对比不同模型的长上下文生成效果我一直在用 kulaaileadhi.cn这个 AI 模型聚合平台来回切模型测试。今天借此聊聊深度使用 Gemini 3.5 辅助编程的一个实战场景30 分钟内给一个 NestJS 项目生成完整的代码注释。为什么选 Gemini 3.5 做这件事写代码一时爽补文档火葬场。——这大概是每个开发者最真实的写照。高质量的 API 文档和代码注释不仅能拯救交接项目的同事更是团队工程规范的底线。手动注释一个中型 NestJS 项目30 个 Controller Service至少需要 4-6 小时。但 Gemini 3.5 凭借 100 万 token 的上下文窗口可以一次性吃下整个项目的源代码直接基于现有代码风格生成注释。这个能力在代码注释场景下优势明显。Gemini 3.5 Flash 在 Terminal-Bench 编码测试上拿了 76.2%速度 289 tokens/s比 Claude Opus 4.7 和 GPT-5.5 快 4 倍以上。价格 1.50/百万token输入、1.50/百万token输入、9.00/百万 token 输出。对注释这种量大但不需要深度推理的任务Flash 版本的性价比极高。准备工作导出项目上下文在提示词设计之前先把项目的关键信息整理好。第一步导出项目目录树。在终端执行tree src/ --prune -I node_modules得到一个简短的目录结构。第二步合并核心代码文件。把需要注释的 Controller、Service、DTO、Module 文件合并为一个长文本。Gemini 3.5 的上下文窗口能轻松容纳整个中型项目。第三步提供项目拓扑。在 Prompt 中明确告诉它哪些是核心文件、哪些是调用上下文参考。这一步很关键——Gemini 3.5 虽然能装下整个项目但如果直接无脑丢二三十个文件注意力机制会产生大海捞针式的衰减。提示词设计约束优先过滤幻觉提示词怎么写决定注释质量。帮我写注释和为每个 Controller 方法生成符合 NestJS 规范的 JSDoc 注释包含 summary、description、param、returns 标签——两个提示词得到的结果差距非常大。我实测通过率最高的一套提示词模板texttext【角色】你是一个精通 NestJS 和 TypeScript 的高级后端工程师。 【上下文】以下是当前项目的目录结构和核心代码文件 src/ ├── modules/ │ ├── user/ │ │ ├── user.controller.ts (核心待注释文件) │ │ ├── user.service.ts (核心待注释文件) │ │ └── dto/ │ │ └── create-user.dto.ts │ └── order/ │ ├── order.controller.ts │ └── order.service.ts ├── common/ │ └── guards/auth.guard.ts (调用上下文参考) 【任务】请为上述所有 Controller 和 Service 文件中的每个公开方法生成完整的 JSDoc 注释。 【规范】 1. 使用 summary 一行概括方法功能 2. 使用 description 详细说明业务逻辑 3. 使用 param 标注每个参数的类型和含义 4. 使用 returns 标注返回值类型和含义 5. 使用 throws 标注可能抛出的异常 6. 对于使用了装饰器的方法如 UseGuards在注释中说明权限要求 【限制】 - 禁止使用 // 保持不变、// 省略其余代码 等占位符 - 即使是没有修改的方法和类成员也必须完整输出 - 我需要直接复制并替换整个文件 - 注释语言使用英文符合 JSDoc 标准规范这个模板有三个关键设计约束优先。把注释规范写死在提示词里避免模型自由发挥。Gemini 3.5 有时会热心地多写两段解释但注释场景我们只需要结构化的 JSDoc 标签。强制无损输出。Gemini 3.5 特别喜欢在生成长文件时使用// 此处省略其余代码的占位符。在自动化 CI/CD 或直接 Copy 代码时这简直是灾难。所以必须在提示词中明确禁止。文件拓扑引导。明确标注哪些是核心待注释文件、哪些是上下文参考。这样模型的注意力会集中在核心文件上上下文参考文件只用来理解调用关系。实战过程分步生成逐文件校验复杂功能拆成小步骤分步生成比一次性描述所有需求效果好。第一轮Controller 层注释约 10 分钟。把所有 Controller 文件一次性喂给 Gemini 3.5让它只处理 Controller 方法的注释。生成的 JSDoc 注释质量很高——summary 精准概括、param 和 returns 类型标注完整、throws 异常说明到位。第二轮Service 层注释约 10 分钟。同样的方式处理 Service 文件。Service 层的注释需要更多业务逻辑描述Gemini 3.5 在这方面表现不错——它能根据代码中的 Prisma 调用和条件判断推断出业务意图。第三轮DTO 和 Guard 注释约 5 分钟。DTO 文件通常较短一次性生成即可。Guard 文件的注释重点是权限说明Gemini 3.5 能正确识别UseGuards装饰器并说明所需角色。第四轮校验和修正约 5 分钟。逐文件检查生成的注释主要关注三个方面实测效率数据环节手动注释Gemini 3.5 辅助效率提升Controller 层12 个文件~90 分钟~10 分钟~89%Service 层10 个文件~80 分钟~10 分钟~87%DTO Guard8 个文件~30 分钟~5 分钟~83%校验和修正~60 分钟~5 分钟~92%总计~4 小时~30 分钟~87%30 分钟搞定一个中型 NestJS 项目的完整代码注释。三个必须注意的坑第一Gemini 3.5 偶尔会发明不存在的参数。对于复杂的 DTO它有时会根据业务语义推测出代码中未定义的字段。校验时重点检查 param 标注是否和代码中的实际参数一致。第二注释语言风格需要约束。如果不指定注释语言Gemini 3.5 默认用英文但偶尔会在英文注释中夹杂中文说明。建议在系统指令中明确写死语言要求。第三Temperature 要调低。代码注释是确定性任务不需要创意。建议将温度值调低至 0.1 或 0防止模型自己发明注释内容。趋势AI 代码注释正在从可选变成标配两个判断。第一代码注释的自动化程度正在快速提升。从 GitHub Copilot 的实时补全注释到 Compodoc 的自动化文档生成再到 Teable 的代码即文档理念整个行业正在把注释从人力密集型工作变成自动化流水线。Gemini 3.5 的 100 万 token 上下文窗口让一次性注释整个项目成为现实。第二混合使用多个模型是当前务实策略。注释这种量大、结构化、不需要深度推理的任务用 Gemini 3.5 Flash 的性价比最高——速度快、价格低。但如果需要注释复杂的业务逻辑或算法实现可以灵活切换到 Claude 或 GPT-5.5 做局部深度注释。通过聚合平台灵活切换比绑定单一模型更稳妥。拿自己的真实项目跑一遍比看任何评测都靠谱。效率数据基于 2026 年 Q2 实测整理模型能力以最新公告为准。提示词模板参考社区最佳实践。
