企业官网建设流程全解析

本文定位：AI Coding / Java 后端 / 研发流程 / 代码验证

示例环境：Java 21、Spring Boot 3.3、Maven、JUnit 5、Docker。具体 Coding Agent 工具会变化，本文关注可迁移的工作方法。

摘要

AI Coding Agent 可以快速阅读仓库、生成代码、修改测试和解释错误，但“能生成代码”不等于“能交付可维护功能”。Java 项目通常包含数据库迁移、权限、事务、消息、配置、接口兼容和部署脚本，一个看似简单的需求可能影响多个边界。把模糊需求直接交给 Agent，常见结果是代码很多、测试很少、异常处理缺失，甚至改动了不该改的文件。

本文把 AI Coding Agent 放进一套受约束的研发流程：先让 Agent 建立仓库地图，再拆分任务和验收标准，先写测试，再小步实现，最后进行构建、静态检查、安全检查和人工 Review。重点不是如何写一条神奇 Prompt，而是如何建立验证闭环。

一、Agent 能做什么，不能替代什么

Agent 的输出是候选修改，最终交付仍然需要编译器、测试、静态分析、运行环境和人来共同验证。

二、从需求到可执行任务

不要把“给系统加一个 AI 问答功能”直接作为任务交给 Agent。先写清楚边界：

目标：为工单详情页增加基于知识库的故障建议。 必须支持：租户隔离、引用文档、超时降级、单元测试。 不允许：直接修改工单状态、访问任意数据库、记录完整敏感文本。 验收：未授权租户无法检索；模型超时返回可理解提示；引用编号可回溯。 范围：先修改 ai-gateway、retrieval、ticket-web 三个模块。

然后让 Agent 先只读分析：目录结构、入口类、配置、测试、依赖、数据库迁移和已有异常处理。第一轮不要让它写代码，先让它列出修改点和不确定性。

三、建立仓库地图

一个合格的仓库地图应包含：

• 模块依赖关系和启动入口。
• Controller、Service、Repository 的调用链。
• 认证、租户和权限上下文如何传递。
• 数据库表和迁移工具。
• 异步任务、消息队列和外部依赖。
• 测试命令、构建命令和本地启动方式。
• 已知技术债和不可触碰的目录。

如果 Agent 不知道项目的异常、权限和测试约定，它可能生成一段“看起来合理”但无法融入现有系统的代码。

四、TDD：先让错误暴露

对于新功能，先写最小验收测试。例如多租户检索的第一条测试应该验证租户隔离，而不是先验证模型回答文本。

@TestvoidshouldOnlyRetrieveChunksFromCurrentTenant(){repository.save(chunk("tenant-a","A文档"));repository.save(chunk("tenant-b","B文档"));List<Evidence>result=service.retrieve(newQuery("设备告警"),auth("tenant-a"));assertThat(result).allMatch(item->item.tenantId().equals("tenant-a"));}

然后测试超时、空结果、引用校验、敏感字段脱敏和模型错误。测试先失败是正常的，它帮助 Agent 和开发者明确交付标准。

五、让 Agent 小步修改

一次只给 Agent 一个可验证任务，例如：

1. 增加RetrievalService接口和租户过滤测试。
2. 实现 PostgreSQL 查询，不修改 Controller。
3. 增加引用 DTO 和校验器。
4. 添加超时和降级测试。
5. 最后接入页面或工作流。

每一步都要求 Agent 说明修改文件、未解决的问题和验证命令。大范围重构会让 Review 失去焦点，也更容易把无关格式变化混入提交。

六、数据库与权限修改必须人工审查

Agent 可以生成迁移脚本，但不能自动决定数据生命周期和回滚策略。检查以下内容：

• 新字段是否允许为空，历史数据如何填充。
• 索引是否与查询条件一致，是否会锁表。
• 租户字段是否出现在所有访问路径。
• 删除和归档是否可恢复。
• 回滚脚本是否真的可执行。
• 生产数据是否需要脱敏或分批迁移。

-- 迁移前先确认已有数据量和租户分布SELECTtenant_id,count(*)FROMai_request_logGROUPBYtenant_id;ALTERTABLEai_request_logADDCOLUMNprompt_versionvarchar(64);CREATEINDEXCONCURRENTLY idx_ai_request_traceONai_request_log(trace_id);

迁移脚本应该说明适用版本、预计耗时和回滚方式。不要让 Agent 在没有环境信息时猜测生产数据库行为。

七、用验证命令约束交付

每次修改至少执行：

mvn-q-DskipTests=falsetestmvn-qverify mvn-qdependency:tree

如果项目有 Checkstyle、SpotBugs、OWASP Dependency-Check、JaCoCo 或集成测试，也应加入验证。Agent 报告“测试通过”不等于你应该相信它，必须查看实际命令输出和失败数量。

对 AI 相关代码，还要补充：评测集回归、Token 成本、超时、模型异常、工具权限和日志脱敏检查。普通单元测试无法覆盖这些运行时行为。

八、代码 Review 的重点

审查 Agent 生成的 Java 代码时，可以按以下顺序：

1. 边界：输入为空、超长、非法枚举和异常响应。
2. 权限：租户、用户、角色和资源归属是否来自可信上下文。
3. 事务：数据库写入和外部调用的顺序、幂等和补偿。
4. 性能：循环查询、无界集合、连接池、超长上下文和重复模型调用。
5. 安全：日志敏感字段、SQL 注入、任意 URL、文件路径和密钥。
6. 可维护性：接口职责、异常类型、命名、测试和配置。

publicAiAnswerask(Queryquery,AuthContextauth){Objects.requireNonNull(auth,"auth");if(query.text()==null||query.text().isBlank()){thrownewInvalidArgumentException("问题不能为空");}if(query.text().length()>2000){thrownewInvalidArgumentException("问题过长");}returngateway.ask(query,auth);}

看似简单的输入校验，往往比让 Agent 写一段复杂 Prompt 更能降低风险。

九、不要把密钥和环境写进 Prompt

Agent 需要知道如何调用服务时，应读取脱敏的配置说明或接口契约，不应把 API Key、数据库密码、内网地址和生产 Token 放进上下文。仓库扫描要检查.env、日志、测试数据和生成文件。

允许读取：接口名称、请求字段、脱敏示例、测试环境地址。 禁止读取：API Key、密码、生产连接串、个人隐私、未授权租户数据。

如果 Agent 工具可以执行命令，应限制工作目录和命令白名单；如果可以修改文件，应明确范围，避免它自动覆盖用户已有改动。

十、提交前的差异审查

先查看git diff，再看文件统计和新增依赖。关注：

• 是否修改了任务范围外的文件。
• 是否出现大面积格式变化。
• 是否删除了原有测试或异常处理。
• 是否新增不必要的依赖。
• 是否把调试代码、临时日志和 TODO 留在生产路径。
• 是否有硬编码密钥、地址和模型名称。

Agent 生成的代码经常“顺手”重命名、格式化或升级依赖，这些变化需要拆分或回退，保证提交容易理解和回滚。

十一、把经验沉淀为项目规则

如果每次都要重复告诉 Agent “不要绕过租户权限”“先写测试”“不要改迁移”，可以把这些约束写入项目的开发说明、贡献指南和自动检查。规则要短、具体、可验证，避免写成一篇无人维护的长文。

对 AI 应用，建议固定记录：

• 可调用工具和风险级别。
• Prompt、模型、知识库和工具版本管理方式。
• 必须通过的评测和安全用例。
• 不能自动执行的高风险动作。
• 本地和 CI 验证命令。

十二、一个可直接复用的验收单

在任务结束时，可以要求 Agent 和开发者共同填写一张验收单：

这张表的价值在于把“Agent 说已经完成”转化为可检查的证据。对于 AI 相关功能，还要附上模型、Prompt、知识库和工具版本，否则下一次复现时很可能得到不同结果。

十三、总结

AI Coding Agent 的价值不是替程序员承担全部责任，而是降低阅读、样板代码、测试和排查的重复成本。真正决定交付质量的仍然是需求边界、架构判断、测试验证、安全审查和变更控制。

在 Java 项目中，最稳妥的工作流是：先读仓库、再拆任务；先写测试、再改实现；小步修改、每步验证；最后审查差异、依赖和安全。代码可以由 Agent 快速生成，但是否正确、是否可维护、是否应该上线，必须由工程流程回答。

读者讨论

如果你正在使用 AI Coding Agent，建议把一次任务拆成“分析、测试、实现、验证、Review”五个阶段，并保留每个阶段的结果，后续复盘会比只保存最终代码更有价值。