← 返回学习路线

SYSTEM

项目代码规范|基于《阿里巴巴Java开发手册(泰山版)》+字节安全生产规范

QuillAgent文档
src/content/notes/projects/04-代码规范.md

项目代码规范|基于《阿里巴巴Java开发手册(泰山版)》+字节安全生产规范

适用项目:桌面智能创作助手(码字工具) 技术栈:SpringBoot3.5.x、Spring‑AI‑1.x‑GA、MyBatis‑Plus、SQLite(xerial‑jdbc)、Electron+Vue3+TipTap 约束背景:单机桌面本地Java后端,绑定127.0.0.1,禁止对外暴露端口;本机纵深防御X‑Local‑Token;密钥只存在单次请求内存;SSE流式;AI大模型调用;SQLite嵌入式数据库;8周业余毕设项目;后端是核心,前端Electron/Vue为辅 分为:【Java后端强制规范】【SQLite数据库规范】【SSE/大模型ModelRouter专项安全规范】【Electron‑Vue前端规范】【Git&CI工程规范】【安全生产红线(零容忍)】【毕设可妥协边界(区分生产标准和毕设现实)】

⚠️重要说明:毕设项目尽量对齐阿里/字节标准,但部分重型生产设施(全链路SkyWalking、复杂限流组件、大规模压测)不做强制,明确划分「必须严格执行」和「毕设可简化,但文档写明妥协点」。

一、Java后端编码规范(对齐阿里Java开发手册泰山版)

1 命名规范(强制)

  1. 包名全部小写,禁止下划线;业务分层严格:com.xxx.writer.config / controller / service / dto / exception / persistence / util / configload
  2. 类名大驼峰;方法、变量小驼峰;常量static final全大写下划线分隔。
  3. DTO区分入参XXXReq、出参XXXResp;禁止通用HashMap/JSONObject做接口入参出参,强类型DTO。
  4. 数据库实体Entity:表名下划线,实体类大驼峰,字段小驼峰;MyBatis‑Plus注解规范。
  5. 自定义业务异常:XXXBizException,携带错误码枚举。
  6. 枚举:错误码ErrorCodeEnum、文体GenreEnum、AI操作OperationEnum,禁止魔法字符串、魔法数字散落在业务代码。

2 控制器 Controller 层【强制】

  1. Controller只做:参数校验、调用Service、组装返回结果;禁止写业务逻辑,禁止直接操作DB、文件、HTTP客户端。
  2. 入参对象必须加@Valid校验;非空、长度、范围校验用JSR‑380注解;业务校验下沉Service。
  3. 统一返回封装对象Result<T>,禁止直接返回原始实体、原始JSON;统一code/message/data/requestId。
  4. 禁止在Controller捕获业务异常,交由@RestControllerAdvice全局异常处理器统一拦截翻译。
  5. 所有业务接口必须校验X‑Local‑Token;健康探测接口/api/status/local‑model、/api/system/info做白名单放行。
  6. Host头校验:只允许localhost / 127.0.0.1;CORS禁止*。

3 Service层规范

  1. Service接口与实现分离,XXXService接口、XXXServiceImpl实现类;业务逻辑全部放在Service。

  2. 禁止在Service中直接new HTTP客户端;所有大模型调用统一经过ModelRouter,唯一出入口。

  3. 事务注解

    @Transactional

    :

    • ✅只加在public方法;
    • ✅红线:事务内部禁止发起网络IO、AI调用、SSE生成,事务仅执行纯数据库操作,快速commit释放SQLite写锁;
    • ✅指定rollbackFor = Exception.class;
  4. 业务禁止直接捕获吞异常;捕获异常必须打印日志log.error("xxx",e),再抛出自定义业务异常;禁止try{}catch(Exception e){}空catch吃掉异常。

  5. 复杂业务拆分小方法;单个方法行数建议不超过80行;过长抽取私有工具方法。

  6. 工具类全部放util包,方法public static,禁止持有成员变量、禁止有状态。

4 DTO / POJO / Entity 规范

  1. Entity数据库实体:禁止业务字段,只做数据库映射;业务输出使用Resp DTO,禁止直接把Entity返回到前端。
  2. 敏感字段:apiKey 绝对不能出现在任何POJO/Entity/DTO成员变量,只能作为方法局部临时变量。
  3. DTO字段使用包装类型(Integer/Long),拒绝基本类型int/long,区分null和0语义。
  4. 禁止使用@Data全套注解给Entity,使用@Getter @Setter @ToString;ToString排除大文本content字段,防止日志打印整篇文档。

5 异常处理规范(阿里强制)

  1. 自定义业务异常BizException,携带ErrorCodeEnum错误码。
  2. 全局异常处理器@RestControllerAdvice,区分:参数校验异常、业务异常、未知系统异常。
  3. ❌禁止:把原始Java异常堆栈直接返回前端;前端只接收友好业务message+错误码,堆栈仅后端日志留存。
  4. ❌禁止:打印完整modelConfig入参对象日志,会输出apiKey;业务层禁止log.info("入参{}", modelConfig)。

6 日志规范(字节安全生产重点,强制)

  1. 使用org.slf4j.Logger,禁止直接System.out / System.err打印。
  2. 生产环境root=INFO,关闭DEBUG/TRACE;开发环境DEBUG。
  3. 日志脱敏实现:使用Logback自定义Layout转换器,字符串正则替换sk‑\*、tvly‑\*、apiKey:"\**\*",不修改HttpServletRequest对象,不包装请求体,避免SSE破坏。
  4. 日志强制携带MDC requestId,便于链路排查。
  5. 禁止日志打印:用户apiKey、search密钥、完整大文档正文(长文本做截断)。
  6. 审计日志INFO级别记录:文档新建/删除/导出、版本回滚、AI调用(记录documentId、genre、mode,不打印密钥、不打印全文)、配置重载。

7 配置规范

  1. 区分application.yml(公共)、application‑dev.yml开发、application‑prod.yml生产profile。
  2. 业务提示词、检规词库全部外置agent.yml;禁止硬编码prompt、检规正则到Java代码。
  3. 废弃WatchService文件热加载;改为「启动加载 + 设置页手动重载按钮」;配置解析失败回滚旧配置,服务不崩溃。
  4. 敏感密钥不进后端配置文件yml;apiKey全部来自前端POST请求体,单次请求局部变量。

8 单元测试规范(毕设妥协)

对齐阿里标准,但考虑8周业余时间,做收敛:

  1. 必测5个核心用例:日志脱敏、ModelRouter分支、自检规则引擎、文档版本hash去重、offset映射工具。
  2. 禁止把真实apiKey写进单元测试,全部Mock。
  3. 单元测试不追求高覆盖率,禁止为了覆盖率写无意义测试用例;其余业务链路靠E2E手工测试。

二、SQLite数据库编码规范(本项目专项,阿里MyBatis‑Plus规范适配嵌入式库)

注意:SQLite不是MySQL,不能直接照搬MySQL开发习惯。

  1. HikariCP强制:maximum‑pool‑size: 1,禁止多连接池,防止database‑locked。
  2. 连接初始化执行PRAGMA:
PRAGMA journal_mode=WAL;
PRAGMA busy_timeout=5000;
PRAGMA foreign_keys=ON;
PRAGMA synchronous=NORMAL;
  1. DDL脚本使用Flyway版本化迁移,禁止程序运行期自动建表。
  2. 主键使用INTEGER PRIMARY KEY AUTOINCREMENT;时间字段用TEXT存储ISO‑8601字符串,不要使用DATETIME(SQLite无该类型)。
  3. 禁止长事务;禁止事务内部包含网络、AI调用。
  4. 定时执行PRAGMA wal_checkpoint(TRUNCATE),防止‑wal文件无限膨胀。
  5. 四张核心表:document / doc_version / prompt_template / material;禁止大字段做where条件查询;大文本content避免索引。
  6. 外键依赖开启foreign_keys=ON;删除文档使用事务级联删除版本记录。
  7. 禁止N+1查询;MyBatis‑Plus避免list()全表查大表。
  8. 备份:业务代码不实现自动备份;文档告知用户手动复制.db文件。

三、SSE + Spring‑AI ModelRouter专项安全&编码规范【本项目最高风险模块,字节安全生产红线】

  1. SSE只使用SseEmitter,禁止引入WebFlux;前端禁用EventSource,统一fetch + ReadableStream + AbortController。
  2. 订阅Spring‑AI返回Flux,必须持有Disposable对象;SSE每10‑15s发送ping心跳;写失败立刻dispose()终止大模型调用,释放资源。
  3. SSE事件严格白名单:仅token / error / complete;禁止透传模型原始输出作为后端指令,防范prompt注入。
  4. apiKey生命周期:仅POST请求体modelConfig传入,方法局部临时变量;禁止赋值给成员变量、禁止存入任何POJO、禁止缓存、禁止日志打印、禁止落库。
  5. ModelRouter作为唯一AI调用入口,所有续写、quick、check、outline、inspire全部走该层;禁止业务Service直接创建WebClient调用大模型。
  6. WebClient必须设置连接超时、读取超时;捕获Broken pipe、429限流,翻译成业务错误码,不把原始第三方异常抛给前端。
  7. LLM返回JSON解析必须做容错;JSON解析失败,丢弃语义结果,只返回规则引擎结果,不能整体接口500。

四、Electron + Vue3 + TipTap前端编码规范(参考字节前端规范)

  1. Electron安全基线强制:contextIsolation:true、nodeIntegration:false、sandbox:true;preload只暴露最小白名单API;禁止渲染进程直接访问node能力。
  2. 禁止在渲染进程console打印apiKey、search密钥;所有密钥仅存localStorage,绝不提交到后端。
  3. SSE统一fetch+ReadableStream+AbortController;可取消AI请求。
  4. TipTap规范:
    • 存库:editor.getHTML();AI/字数统计/自检使用editor.getText()纯文本投影。
    • 纯文本offset ↔ ProseMirror pos映射写独立工具函数,写单元测试。
    • 自检:仅点击按钮一次性生成Decoration标记,用户编辑后清空标记,不做实时输入标红。
    • 所有AI替换正文操作,必须通过TipTap transaction执行,进入编辑器撤销栈。
  5. 草稿缓存使用IndexedDB;不使用容量受限localStorage存储大文档正文。
  6. 禁止硬编码后端端口;后端地址通过配置读取。
  7. 主进程spawn启动java:shell:false;java作为直接子进程;tree‑kill兜底杀进程树;禁止shell包装,避免孤儿进程。
  8. 后端启动参数--writer.data‑dir传递数据目录;所有db、token文件、agent.yml全部放在该目录,禁止写死相对路径。

五、Git、工程构建规范(阿里/字节工程实践)

  1. Git commit规范:feat/fix/refactor/test/docs/security;禁止大杂烩commit。
  2. gitignore必须屏蔽:本地yml配置、日志目录、sqlite db/wal/shm文件、node_modules、jlink产物;严禁把密钥、db提交到仓库。
  3. Maven版本锁定:Spring‑Boot 3.5.x,Spring‑AI 1.x GA,禁止升级Spring‑AI2.0(基于Boot4,不兼容);所有第三方依赖版本统一管理,避免版本冲突。
  4. 开发环境:docker‑compose仅用于开发调试;绝对不能作为普通用户桌面交付方案。
  5. 打包:使用jlink裁剪JRE,随Electron extraResources分发;不依赖用户预装JDK。
  6. 禁止把Ollama大模型打进安装包;用户自行pull预训练模型。

六、🚨安全生产零容忍红线(违反直接不合格,毕设也不能妥协)

参考字节内部应用安全编码规范,本项目单机桌面也必须遵守:

  1. ❌严禁apiKey、第三方搜索密钥落库、写入配置文件、打印日志、异常堆栈。
  2. ❌严禁后端绑定0.0.0.0,后端必须绑定127.0.0.1;禁止把8080端口对外暴露公网。
  3. ❌禁止直接把大模型返回内容当做后端指令执行(防prompt注入)。
  4. ❌禁止shell:true拉起Java进程,防止Windows产生孤儿进程。
  5. ❌禁止捕获吞异常:try {...} catch(Exception e) {}空捕获,必须打日志再抛业务异常。
  6. ❌禁止在事务中执行网络请求、AI调用、SSE生成。
  7. ❌SSE禁止输出白名单之外事件类型。
  8. ❌禁止打印完整modelConfig对象到日志。
  9. ❌Electron开启nodeIntegration: true;关闭contextIsolation。
  10. ❌禁止硬编码密钥、写死文件相对路径。

七、毕设项目现实妥协边界(重点,区分生产环境标准)

本项目是毕设单机桌面原型,不是面向公网SaaS生产系统,下面几条是允许妥协,但是必须写进论文《系统不足与展望》,明确说明,不能当做生产级实现。

  1. 不引入SkyWalking全链路追踪、Prometheus监控;仅MDC requestId做简单链路日志。
  2. 不做复杂限流组件;仅在业务层简单做参数maxTokens上限校验,无分布式限流。
  3. 不做完整密码加密、多租户(本项目无登录)。
  4. 单元测试只覆盖5个核心工具类,不追求高测试覆盖率;业务靠手工E2E测试。
  5. X‑Local‑Token仅防御浏览器网页DNS‑rebinding、跨页fetch攻击;不防御本机已经植入恶意程序,威胁模型文档写明。
  6. SQLite不做集群、主从,单机单进程使用。
  7. 没有自动数据库备份;依靠用户手动复制db文件。