在上一篇《AI重构低代码：当我们在谈论选型时，技术负责人真正该关注什么？》中，我们探讨了架构选型的重要性。接下来，我们将目光聚焦于 JDK 21 + Spring Boot 3 + Vue 3 这一主流技术栈下的工程落地实践，聊聊如何通过“代码规范”降低团队协作成本，真正实现企业的降本增效。

当我们选择“单体架构 + 多包模块拆分”这条务实的路线时，如果没有严格的规范约束，代码极易演变成难以维护的“大泥球”。而在引入 AI 辅助编程后，规范更是成为了 AI 准确理解业务意图的“契约”。抛开繁杂的工程化流程，聚焦于纯代码编写本身，一套行之有效的规范体系主要包含以下三个核心维度:一、遵循行业共识，降低认知负荷

代码不仅是写给机器执行的，更是写给人看的。我们应优先沿用业界最佳实践，统一排版约定与语义化命名法则，摒弃模糊缩写，做到“见名知意”，从而大幅降低跨团队协作时的沟通与阅读成本。

一、 落地高内聚复用，消除冗余设计

敏锐识别并践行 DRY（Don't Repeat Yourself）原则，将重复任务抽象为可复用的公共模块；严格落实单一职责原则（SRP），控制函数长度与嵌套层级。同时，强调交互行为的一致性设计，养成定期清理死代码的习惯，抵制过度设计，保持代码库精简。

二、 坚守防御性设计与异常处理底线

秉持“不信任外部输入”的原则，落实前后端双重规则校验。前端尽早进行基础格式校验以提供即时反馈，后端则作为最终防线进行严格二次校验。此外，需建立优雅的容错机制，明确异常捕获边界，严禁直接吞掉异常，确保系统在突发状况下能优雅降级而非直接宕机。

理论层面的考量固然重要，但在实际项目中，规范还包含了从目录划分、架构封装到交互一致性的方方面面。接下来，我将结合《鹿鲸项目管理工具》的研发实践，分享具体的规范落地方案。

1、 数据库设计规范

本项目采用 RDS for PostgreSQL 数据库，在开发过程中严格遵守以下设计准则：

1.Schema创建规则

• 命名准则：严格使用小写字母、下划线组合（snake_case）。禁止使用双引号包围对象名，避免使用pg_等系统前缀。

• 项目约定：根据项目规范约定，Schema名称以dw_前缀开始，Schema名称和Java拆包中业务功能模块包一一对应，并且每个schema都必须写好注释并指定好所属用户。

2、表及字段创建规则

• 命名准则a.基础规范：严格使用小写字母、下划线组合（snake_case）。禁止使用双引号包围对象名，避免使用pg_或pgxc_等系统前缀。

  b.长度限制：对象名（表名、字段名）长度不得超过63个字符。

  c.关键字避让：严禁使用SQL关键字作为对象名

• 主键策略

• 所有表必须包含主键。本项目统一使用id varchar(36) 作为主键，主键统一通常情况下采用程序的NanoID自动生成值。

  说明：统一约定主键字段名称，方便后续前后端一些常用操作接口和功能模块封装。

• 索引命名

  a.普通索引：idx_{table_name}_{column_name}

b.唯一索引：uk_{table_name}_{column_name}c.联合索引：idx_{table_name}_{col1}_{col2}索引命名过程中，长度过长，可以根据实际情况缩写列名。

• 项目约定项目建设中，统一约定了以下字段：

  字段名	数据类型	说明/备注
  id	varchar(36)	主键
  create_user_id	varchar(36)	创建人ID
  create_user_name	varchar(128)	创建人姓名
  created_time	timestamp	创建时间
  modify_user_id	varchar(36)	更新人ID
  modify_user_name	varchar(128)	更新人姓名
  modified_time	timestamp	更新时间
  parent_id	varchar(36)	父节点ID
  py_code	varchar(64)	拼音码
  wb_code	varchar(64)	五笔码
  sort_no	integer	排序号

根据数据库表关联关系和数据存储内容分析，我们将表分为四类表：a.主表：主要用于存储基础信息，如角色表、用户表、部门表等每张业务主表必须包含以下字段：id、create_user_id、create_user_name、created_time、modify_user_id、modify_user_name、 modified_time、py_code、wb_code

b.关联表：主要用于存储关系信息，如角色和用户之间的关联关系表

每张关联关系表中必须包含以下字段：id、create_user_id、create_user_name、create_time

c.树结构表

特殊说明：表中必须包含审计字段，审计字段冗余用户姓名，减少操作时的关联查询。

2、 Java 开发规范

除系统内部特殊约定外，优先遵循阿里出版的《Java开发手册-黄山版》。

1. 分层架构与包路径约定业务模块包中遵循严格的分层架构，各层职责明确：

● 表现层 (Controller)：继承OneEntityController，负责接收请求、参数校验及返回结果，不处理业务逻辑。

● 业务层 (Service)：接口继承IOneEntityService，实现类继承OneEntityServiceImpl，负责核心业务逻辑。

● 持久层 (Mapper)：继承 MyBatis-Flex 的BaseMapper。

● 数据对象 (PO)：继承BasePO/MasterPO，使用@Table映射数据库表，字段使用@Column指定类型。

● 视图对象 (VO)：继承BaseVO/MasterVO，用于向前端展示数据。

● 传输对象 (DTO)：分为 Add（新增）、Modify（修改）、Search（查询）。新增/修改 DTO 需分别继承InsertDTO/UpdateDTO。

2. RESTful API 设计规范 （严格按照restful api执行）

例如：

3. 全局输出与控制器规范

● 全局统一输出：通过ResponseBodyAdvice对输出格式进行统一封装。如果不需要对外输出统一包装，可以在 Controller 方法上添加@NoResultBody注解。

● Controller 规范：标准模块 Controller 应继承基类，使用@Operation(Swagger) 描述接口功能，使用@Validated进行参数校验，并通过@ResultBodySuccessMsg统一返回成功提示，使用@OperationLog记录操作日志。

3、 前端开发规范

前端的核心原则是：组合式 API + TypeScript + 状态管理轻量化。

1. 技术栈约束

● TypeScript 强制：所有组件、API 请求、Hooks 必须有类型定义。禁止使用any，除非处理第三方库的复杂类型（需加// @ts-ignore注释并说明原因）。

● Composition API：统一使用<script setup lang="ts">语法糖。逻辑复用必须通过 composables（自定义 Hooks）实现，如useUserStore、useTaskList。

2. 状态管理与 API 调用

● Pinia 规范：按业务模块化划分 Store。禁止在 Store 中直接操作 DOM 或调用浏览器 API（如localStorage），应封装在 utils 或 composables 中。

● API 层封装：使用 axios 或 fetch 封装统一的请求拦截器（处理 Token、错误码统一提示）。接口返回类型必须与后端Result<T>保持一致，使用泛型定义响应数据结构。例如在api/task.ts中定义getTaskList(params: TaskQuery): Promise<Result<Task[]>>。

3. 组件与样式规范

● UI 组件库：基于 Element Plus 进行二次封装，形成业务组件库（如<DwDictSelector />）。

● 样式隔离：组件样式必须使用 scoped 或 CSS Modules，避免全局污染。

● 交互一致性：表单提交统一使用 loading 状态防止重复提交（按钮或者表单loading)；列表分页统一使用current和pageSize参数名，后端返回total；网络错误或业务错误需有统一的 Toast 提示，严禁静默失败。

如果说上一篇的“单体模块化”赋予了系统敏捷的身手，那么本篇“严格的代码规范”则为这具躯体装上了安全的护栏。在 AI 时代，我们无需再死记硬背繁杂的语法，却更需要深耕架构思维与规范总结。把重复繁重的编码任务交给 AI 去狂奔，但架构的灵魂与规范的精髓，必须由我们自己牢牢把控。

当然一篇文章很难详尽的介绍整个项目的研发规范，这里只是抛砖引玉，如果大家有好的研发规范，欢迎一起探讨，共同进步。

下期预告：接下来我将分享如何利用这套规范进行实战开发，我将带领代价进入架构封装第一步，敬请期待！

参考资料

【1】《PostgreSQL 18.4 Documentation》官网文档

【2】《Java开发手册-黄山版》，2022年，阿里巴巴发布

【3】《RESTful API 设计规范指南》，阮一峰