当前位置：首页 > news >正文

【AI 编辑器开发规范 v2.1 版】—— 为 AI 时代的敏捷开发而生

news 2026/5/12 9:06:42

最近在用AI写代码，效率高是真的高，但坑也是真的多——SQL没索引、异常被吞、配置写死，上线就出问题。

所以整理了一份《AI编辑器开发规范》，把开发流程、代码质量、调试协作这些容易踩坑的地方都理清楚了。主打一个：让AI帮忙，但不被AI坑。

核心原则：高效、可靠、可维护。本规范旨在平衡 AI 生成代码的效率与人工审查的严谨性，保障个人及小团队的开发节奏与交付质量。

测试先行（TDD 思维）：功能开发前或开发中，必须同步编写单元测试或集成测试，并完成自测。严禁仅实现“快乐路径”而不覆盖异常场景。
启动极速化：开发环境配置必须遵循“一键运行”原则（如 Java 直接运行 main 方法、Python 执行单一脚本、Node 调用 start 命令）。禁止依赖复杂的本地容器或需要多步手动干预才能启动的环境。
原子化提交：代码提交应遵循“原子性”原则，即每次提交只解决一个问题、实现一个完整的小功能或修复一个 Bug。禁止一次性提交数百行包含多个不相关功能的代码，确保提交历史清晰可回溯，便于 Code Review 或版本回滚。
强迫症式整洁：AI 生成代码或手动编码后，必须执行格式化、去除死代码（注释掉的代码块）、消除编译警告（Warning）。保持代码风格如一人所写。
复用优先（DRY原则）：开发前先检索现有代码库。通用工具类、UI 组件、Hooks 等优先复用或重构现有代码，杜绝重复造轮子导致的维护地狱。

严格环境隔离：开发 (Dev)、测试 (Test)、生产 (Prod) 环境的配置（数据库连接、缓存地址、API 密钥）必须物理隔离。严禁在开发时连接生产数据库，或在生产环境开启调试模式。
环境自适应（智能切换）：代码应能根据运行环境变量自动加载对应配置（如application-dev.yml或.env.local）。严禁在代码中手动修改常量值来切换环境，杜绝误提交导致的生产事故。
配置外部化（12-Factor 法则）：所有可变配置（如第三方密钥、文件存储路径、线程池大小）必须外置于配置文件、环境变量或配置中心。禁止在代码中硬编码任何业务常量以外的值。
依赖可追溯（拉之即跑）：新增任何第三方依赖（Jar包、NPM包）或修改构建脚本，必须在提交信息或注释中说明用途。确保团队成员git pull后，执行标准命令即可安装依赖并成功运行，无需额外询问。

清晰的意图注释：接口定义、复杂算法、设计原因（Why）、特殊业务逻辑必须加注释。代码即文档，但注释解释“为什么这么做”比“做了什么”更重要。
AI 代码审查机制（红线）：绝对禁止直接复制粘贴不理解原理的 AI 生成代码。所有 AI 生成的代码必须经过人工审查：
- 审查点：是否存在逻辑漏洞？有无资源未关闭？并发场景是否安全？是否符合本规范？
- 原则：宁可不复用 AI 代码，也不引入不可控的技术债务。
安全编码底线：
- 数据操作：涉及事务的方法需确保原子性，关注索引使用情况，使用预编译或 ORM 防 SQL 注入，上线前 review 慢 SQL 日志。
- 输入校验：坚信“前端传递的数据皆不可信”。所有接口入参（包括内部 Feign 调用）必须校验非空、格式、长度、范围。
- 异常处理：禁止仅e.printStackTrace()或打印日志后不处理。异常必须被妥善捕获、事务回滚（如需），并向调用方返回结构统一、语义明确的错误信息。
基础性能意识：避免在循环中调用数据库或远程接口（N+1问题），避免重复计算，合理使用缓存。性能敏感代码需进行简单的压力自测。

调试友好（万能开关）：开发环境应提供“调试模式”，允许临时跳过繁琐认证（如短信验证码、图形验证码、第三方 OAuth 重定向），或 mock 第三方接口返回。但必须确保开关默认关闭，且在测试/生产环境强制开启真实校验逻辑。
前端鲁棒性（体验兜底）：前端不能假设接口永远返回理想数据。必须处理：
- 空状态：列表没数据时的占位提示。
- 加载中：发起请求时的骨架屏或 Loading 动画。
- 错误态：接口报错或网络超时时的友好提示与重试机制。
接口契约即文档：修改或新增接口，必须同步更新 Swagger 注解、YApi 文档或 Markdown 文档。请求/响应示例必须清晰，字段变更需标注废弃或新增原因，确保前后端联调零障碍。
日志分级（可观测性）：
- INFO：记录关键业务流程节点（如“用户下单成功，订单号：xxx”）、启动参数。
- ERROR：必须包含完整的堆栈信息及上下文参数（如userId、orderId），确保仅凭日志即可定位问题，避免因日志不全而被迫复现。

提交代码至远程仓库前，请默念并执行以下检查：

全量构建与自测：本地完整运行构建命令（如mvn clean install或npm run build），并启动应用进行冒烟测试，确认新功能正常且未影响主流程（如登录、注册）。
代码冲突解决：提交前先从目标分支（如dev）拉取最新代码合并，解决所有冲突，确保本地分支可被 fast-forward 或干净合并。
规范速览：快速对照本规范，检查是否有明显遗漏（如配置没外置？没写注释？没加日志？）。

结束语：规范不是束缚，而是为了让 AI 更听话，让团队更自由。欢迎大家在实践中持续迭代 v3、v4 版。