SYSTEM
项目代码规范|基于《阿里巴巴Java开发手册(泰山版)》+字节安全生产规范
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 命名规范(强制)
- 包名全部小写,禁止下划线;业务分层严格:
com.xxx.writer.config / controller / service / dto / exception / persistence / util / configload - 类名大驼峰;方法、变量小驼峰;常量
static final全大写下划线分隔。 - DTO区分入参
XXXReq、出参XXXResp;禁止通用HashMap/JSONObject做接口入参出参,强类型DTO。 - 数据库实体Entity:表名下划线,实体类大驼峰,字段小驼峰;MyBatis‑Plus注解规范。
- 自定义业务异常:
XXXBizException,携带错误码枚举。 - 枚举:错误码
ErrorCodeEnum、文体GenreEnum、AI操作OperationEnum,禁止魔法字符串、魔法数字散落在业务代码。
2 控制器 Controller 层【强制】
- Controller只做:参数校验、调用Service、组装返回结果;禁止写业务逻辑,禁止直接操作DB、文件、HTTP客户端。
- 入参对象必须加
@Valid校验;非空、长度、范围校验用JSR‑380注解;业务校验下沉Service。 - 统一返回封装对象
Result<T>,禁止直接返回原始实体、原始JSON;统一code/message/data/requestId。 - 禁止在Controller捕获业务异常,交由
@RestControllerAdvice全局异常处理器统一拦截翻译。 - 所有业务接口必须校验
X‑Local‑Token;健康探测接口/api/status/local‑model、/api/system/info做白名单放行。 - Host头校验:只允许
localhost / 127.0.0.1;CORS禁止*。
3 Service层规范
-
Service接口与实现分离,
XXXService接口、XXXServiceImpl实现类;业务逻辑全部放在Service。 -
禁止在Service中直接new HTTP客户端;所有大模型调用统一经过
ModelRouter,唯一出入口。 -
事务注解
@Transactional:
- ✅只加在public方法;
- ✅红线:事务内部禁止发起网络IO、AI调用、SSE生成,事务仅执行纯数据库操作,快速commit释放SQLite写锁;
- ✅指定
rollbackFor = Exception.class;
-
业务禁止直接捕获吞异常;捕获异常必须打印日志
log.error("xxx",e),再抛出自定义业务异常;禁止try{}catch(Exception e){}空catch吃掉异常。 -
复杂业务拆分小方法;单个方法行数建议不超过80行;过长抽取私有工具方法。
-
工具类全部放
util包,方法public static,禁止持有成员变量、禁止有状态。
4 DTO / POJO / Entity 规范
- Entity数据库实体:禁止业务字段,只做数据库映射;业务输出使用Resp DTO,禁止直接把Entity返回到前端。
- 敏感字段:
apiKey绝对不能出现在任何POJO/Entity/DTO成员变量,只能作为方法局部临时变量。 - DTO字段使用包装类型(Integer/Long),拒绝基本类型int/long,区分null和0语义。
- 禁止使用
@Data全套注解给Entity,使用@Getter @Setter @ToString;ToString排除大文本content字段,防止日志打印整篇文档。
5 异常处理规范(阿里强制)
- 自定义业务异常
BizException,携带ErrorCodeEnum错误码。 - 全局异常处理器
@RestControllerAdvice,区分:参数校验异常、业务异常、未知系统异常。 - ❌禁止:把原始Java异常堆栈直接返回前端;前端只接收友好业务message+错误码,堆栈仅后端日志留存。
- ❌禁止:打印完整modelConfig入参对象日志,会输出apiKey;业务层禁止
log.info("入参{}", modelConfig)。
6 日志规范(字节安全生产重点,强制)
- 使用
org.slf4j.Logger,禁止直接System.out / System.err打印。 - 生产环境
root=INFO,关闭DEBUG/TRACE;开发环境DEBUG。 - 日志脱敏实现:使用Logback自定义Layout转换器,字符串正则替换
sk‑\*、tvly‑\*、apiKey:"\**\*",不修改HttpServletRequest对象,不包装请求体,避免SSE破坏。 - 日志强制携带MDC
requestId,便于链路排查。 - 禁止日志打印:用户apiKey、search密钥、完整大文档正文(长文本做截断)。
- 审计日志INFO级别记录:文档新建/删除/导出、版本回滚、AI调用(记录documentId、genre、mode,不打印密钥、不打印全文)、配置重载。
7 配置规范
- 区分
application.yml(公共)、application‑dev.yml开发、application‑prod.yml生产profile。 - 业务提示词、检规词库全部外置
agent.yml;禁止硬编码prompt、检规正则到Java代码。 - 废弃WatchService文件热加载;改为「启动加载 + 设置页手动重载按钮」;配置解析失败回滚旧配置,服务不崩溃。
- 敏感密钥不进后端配置文件yml;apiKey全部来自前端POST请求体,单次请求局部变量。
8 单元测试规范(毕设妥协)
对齐阿里标准,但考虑8周业余时间,做收敛:
- 必测5个核心用例:日志脱敏、ModelRouter分支、自检规则引擎、文档版本hash去重、offset映射工具。
- 禁止把真实apiKey写进单元测试,全部Mock。
- 单元测试不追求高覆盖率,禁止为了覆盖率写无意义测试用例;其余业务链路靠E2E手工测试。
二、SQLite数据库编码规范(本项目专项,阿里MyBatis‑Plus规范适配嵌入式库)
注意:SQLite不是MySQL,不能直接照搬MySQL开发习惯。
- HikariCP强制:
maximum‑pool‑size: 1,禁止多连接池,防止database‑locked。 - 连接初始化执行PRAGMA:
PRAGMA journal_mode=WAL;
PRAGMA busy_timeout=5000;
PRAGMA foreign_keys=ON;
PRAGMA synchronous=NORMAL;
- DDL脚本使用Flyway版本化迁移,禁止程序运行期自动建表。
- 主键使用
INTEGER PRIMARY KEY AUTOINCREMENT;时间字段用TEXT存储ISO‑8601字符串,不要使用DATETIME(SQLite无该类型)。 - 禁止长事务;禁止事务内部包含网络、AI调用。
- 定时执行
PRAGMA wal_checkpoint(TRUNCATE),防止‑wal文件无限膨胀。 - 四张核心表:
document / doc_version / prompt_template / material;禁止大字段做where条件查询;大文本content避免索引。 - 外键依赖开启
foreign_keys=ON;删除文档使用事务级联删除版本记录。 - 禁止N+1查询;MyBatis‑Plus避免
list()全表查大表。 - 备份:业务代码不实现自动备份;文档告知用户手动复制
.db文件。
三、SSE + Spring‑AI ModelRouter专项安全&编码规范【本项目最高风险模块,字节安全生产红线】
- SSE只使用
SseEmitter,禁止引入WebFlux;前端禁用EventSource,统一fetch + ReadableStream + AbortController。 - 订阅Spring‑AI返回Flux,必须持有Disposable对象;SSE每10‑15s发送ping心跳;写失败立刻
dispose()终止大模型调用,释放资源。 - SSE事件严格白名单:仅
token / error / complete;禁止透传模型原始输出作为后端指令,防范prompt注入。 apiKey生命周期:仅POST请求体modelConfig传入,方法局部临时变量;禁止赋值给成员变量、禁止存入任何POJO、禁止缓存、禁止日志打印、禁止落库。- ModelRouter作为唯一AI调用入口,所有续写、quick、check、outline、inspire全部走该层;禁止业务Service直接创建WebClient调用大模型。
- WebClient必须设置连接超时、读取超时;捕获
Broken pipe、429限流,翻译成业务错误码,不把原始第三方异常抛给前端。 - LLM返回JSON解析必须做容错;JSON解析失败,丢弃语义结果,只返回规则引擎结果,不能整体接口500。
四、Electron + Vue3 + TipTap前端编码规范(参考字节前端规范)
- Electron安全基线强制:
contextIsolation:true、nodeIntegration:false、sandbox:true;preload只暴露最小白名单API;禁止渲染进程直接访问node能力。 - 禁止在渲染进程console打印apiKey、search密钥;所有密钥仅存
localStorage,绝不提交到后端。 - SSE统一
fetch+ReadableStream+AbortController;可取消AI请求。 - TipTap规范:
- 存库:
editor.getHTML();AI/字数统计/自检使用editor.getText()纯文本投影。 - 纯文本offset ↔ ProseMirror pos映射写独立工具函数,写单元测试。
- 自检:仅点击按钮一次性生成Decoration标记,用户编辑后清空标记,不做实时输入标红。
- 所有AI替换正文操作,必须通过TipTap transaction执行,进入编辑器撤销栈。
- 存库:
- 草稿缓存使用IndexedDB;不使用容量受限localStorage存储大文档正文。
- 禁止硬编码后端端口;后端地址通过配置读取。
- 主进程spawn启动java:
shell:false;java作为直接子进程;tree‑kill兜底杀进程树;禁止shell包装,避免孤儿进程。 - 后端启动参数
--writer.data‑dir传递数据目录;所有db、token文件、agent.yml全部放在该目录,禁止写死相对路径。
五、Git、工程构建规范(阿里/字节工程实践)
- Git commit规范:
feat/fix/refactor/test/docs/security;禁止大杂烩commit。 - gitignore必须屏蔽:本地yml配置、日志目录、sqlite db/wal/shm文件、node_modules、jlink产物;严禁把密钥、db提交到仓库。
- Maven版本锁定:
Spring‑Boot 3.5.x,Spring‑AI 1.x GA,禁止升级Spring‑AI2.0(基于Boot4,不兼容);所有第三方依赖版本统一管理,避免版本冲突。 - 开发环境:docker‑compose仅用于开发调试;绝对不能作为普通用户桌面交付方案。
- 打包:使用jlink裁剪JRE,随Electron extraResources分发;不依赖用户预装JDK。
- 禁止把Ollama大模型打进安装包;用户自行pull预训练模型。
六、🚨安全生产零容忍红线(违反直接不合格,毕设也不能妥协)
参考字节内部应用安全编码规范,本项目单机桌面也必须遵守:
- ❌严禁apiKey、第三方搜索密钥落库、写入配置文件、打印日志、异常堆栈。
- ❌严禁后端绑定
0.0.0.0,后端必须绑定127.0.0.1;禁止把8080端口对外暴露公网。 - ❌禁止直接把大模型返回内容当做后端指令执行(防prompt注入)。
- ❌禁止
shell:true拉起Java进程,防止Windows产生孤儿进程。 - ❌禁止捕获吞异常:
try {...} catch(Exception e) {}空捕获,必须打日志再抛业务异常。 - ❌禁止在事务中执行网络请求、AI调用、SSE生成。
- ❌SSE禁止输出白名单之外事件类型。
- ❌禁止打印完整modelConfig对象到日志。
- ❌Electron开启nodeIntegration: true;关闭contextIsolation。
- ❌禁止硬编码密钥、写死文件相对路径。
七、毕设项目现实妥协边界(重点,区分生产环境标准)
本项目是毕设单机桌面原型,不是面向公网SaaS生产系统,下面几条是允许妥协,但是必须写进论文《系统不足与展望》,明确说明,不能当做生产级实现。
- 不引入SkyWalking全链路追踪、Prometheus监控;仅MDC requestId做简单链路日志。
- 不做复杂限流组件;仅在业务层简单做参数maxTokens上限校验,无分布式限流。
- 不做完整密码加密、多租户(本项目无登录)。
- 单元测试只覆盖5个核心工具类,不追求高测试覆盖率;业务靠手工E2E测试。
- X‑Local‑Token仅防御浏览器网页DNS‑rebinding、跨页fetch攻击;不防御本机已经植入恶意程序,威胁模型文档写明。
- SQLite不做集群、主从,单机单进程使用。
- 没有自动数据库备份;依靠用户手动复制db文件。