0 Fork 0

Files

T

oneao f4c7413dc6 20260823210241

2026-08-23 21:02:41 +08:00

14 KiB

Raw Blame History

开发规范

**本文引用的文件** - [fms-vue/.oxlintrc.json](file://fms-vue/.oxlintrc.json) - [fms-vue/.oxfmtrc.json](file://fms-vue/.oxfmtrc.json) - [fms-vue/package.json](file://fms-vue/package.json) - [fms-vue/src/main.js](file://fms-vue/src/main.js) - [fms-vue/src/App.vue](file://fms-vue/src/App.vue) - [fms-api/pom.xml](file://fms-api/pom.xml) - [fms-api/src/main/resources/application.yaml](file://fms-api/src/main/resources/application.yaml) - [fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java) - [fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java) - [fms-api/src/main/java/cn/g3soft/fmsapi/controller/DataController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/DataController.java) - [fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java) - [fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java) - [fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java) - [fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java)

简介

本规范面向FMS项目的开发与维护，统一前后端代码风格、模块组织与质量保障流程。内容覆盖：

JavaScript/Vue 代码风格与命名约定、文件组织、注释标准
Vue 组件开发最佳实践（结构设计、Props、事件、样式）
后端 Java 分层规范（Controller/Service/Repository）、异常处理、日志记录
代码质量工具配置与使用（Oxlint、OxFmt）
模块划分原则与目录结构规范

项目结构

仓库采用多模块组织：

fms-vue：前端工程，基于 Vue 3 + Vite + Pinia，使用 Oxlint/OxFmt 进行代码检查与格式化
fms-api：后端工程，基于 Spring Boot 4.x，提供认证、数据、文件等 API
其他辅助目录用于演示、测试与迁移脚本

graph TB
subgraph "前端 fms-vue"
A["src/main.js"]
B["src/App.vue"]
C[".oxlintrc.json"]
D[".oxfmtrc.json"]
E["package.json"]
end
subgraph "后端 fms-api"
F["application.yaml"]
G["pom.xml"]
H["FmsApiApplication.java"]
I["controller/*"]
J["service/*"]
K["exception/*"]
end
A --> B
C --> A
D --> A
E --> A
H --> I
I --> J
I --> K
F --> H
G --> H

图表来源

章节来源

核心组件

前端应用入口与启动流程：main.js 负责创建应用、注册插件、路由就绪后挂载；App.vue 作为根组件仅渲染当前路由
后端应用入口：FmsApiApplication 初始化雪花ID生成器并启动Spring容器
配置中心：application.yaml 定义服务端口、上下文路径、JWT、数据库连接池、文件存储策略等

章节来源

架构总览

前后端通过HTTP交互，前端通过Pinia管理状态，后端以Spring MVC暴露REST接口，统一异常处理与鉴权。

sequenceDiagram
participant U as "用户浏览器"
participant FE as "Vue应用(main.js)"
participant BE as "Spring Boot(FmsApiApplication)"
participant CTRL as "Controller层"
participant SVC as "Service层"
participant DB as "数据库"
U->>FE : 访问页面
FE->>FE : 路由就绪、主题同步
FE-->>U : 挂载根组件(App.vue)
U->>BE : HTTP请求(/api/...)
BE->>CTRL : 分发到对应控制器
CTRL->>SVC : 调用业务服务
SVC->>DB : 读写数据
DB-->>SVC : 结果
SVC-->>CTRL : 返回业务对象
CTRL-->>U : JSON响应或错误

图表来源

详细组件分析

前端代码风格与质量工具

代码检查：使用 Oxlint，启用 vue、unicorn、oxc 插件；correctness 为 error，suspicious 为 warn；浏览器环境默认开启；vite.config.js 单独启用 node 环境
代码格式化：使用 OxFmt，行宽100，不加分号，单引号，尾随逗号全量
脚本命令：lint、lint:fix、fmt、fmt:check、build、test 等

flowchart TD
Start(["开发者提交代码"]) --> Lint["运行 oxlint<br/>校验规则"]
Lint --> |通过| Fmt["运行 oxfmt --check<br/>格式检查"]
Lint --> |失败| Fix["运行 oxlint --fix<br/>自动修复"]
Fix --> Fmt
Fmt --> |通过| Build["构建与测试"]
Fmt --> |失败| ReFmt["运行 oxfmt --write<br/>自动格式化"]
ReFmt --> Build

图表来源

章节来源

Vue 组件开发规范

组件结构：推荐单文件组件 .vue，模板、脚本、样式分离；根组件 App.vue 仅负责路由渲染与可选的性能监控浮层
Props 定义：在 <script setup> 中使用 defineProps 明确类型与默认值，避免隐式 any
事件处理：优先使用 emits 声明事件；组合式函数封装复用逻辑（composables）
样式编写：全局样式集中于 styles/index.css；组件级样式使用 scoped 或模块化；主题通过 CSS 变量与类名切换
状态管理：使用 Pinia 管理跨组件状态，结合持久化插件恢复主题等设置

classDiagram
class AppVue {
+template : "#app"
+router-view
+FpsMonitor(条件渲染)
}
class MainJS {
+createApp()
+use(Pinia, Router)
+initThemeSync()
+bootstrap()
}
AppVue <.. MainJS : "被挂载"

图表来源

章节来源

后端 Java 开发规范

分层组织
- Controller：接收HTTP请求，参数校验，委托Service处理
- Service：业务编排与事务边界
- Repository/DAO：数据访问（本项目通过JDBC/Druid访问）
异常处理：集中式异常处理器 GlobalExceptionHandler 统一捕获并返回标准错误体
日志记录：建议按模块与级别输出关键操作与异常堆栈
配置管理：application.yaml 管理服务端口、上下文路径、JWT、数据库连接池、文件存储策略

sequenceDiagram
participant Client as "客户端"
participant AuthCtrl as "AuthController"
participant AuthService as "AuthService"
participant DB as "数据库"
Client->>AuthCtrl : POST /api/auth/login
AuthCtrl->>AuthService : 验证凭据
AuthService->>DB : 查询用户信息
DB-->>AuthService : 用户数据
AuthService-->>AuthCtrl : 登录结果
AuthCtrl-->>Client : JWT令牌或错误

图表来源

章节来源

数据保存与变更追踪

DataSaveService 负责数据落库与变更追踪，确保一致性
建议在Service层对批量操作进行事务控制，并在异常时回滚

flowchart TD
Start(["开始保存"]) --> Validate["参数与权限校验"]
Validate --> |通过| Save["执行保存/更新"]
Validate --> |失败| ReturnErr["返回错误"]
Save --> Track["记录变更日志"]
Track --> Commit{"是否成功?"}
Commit --> |是| Done(["完成"])
Commit --> |否| Rollback["回滚并抛出异常"]
Rollback --> Done

图表来源

fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java

章节来源

fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java

依赖分析

前端依赖：Vue 3、Vue Router、Pinia、Axios、Dayjs、stk-table-vue 等；开发依赖包含 Vite、Vitest、Oxlint、OxFmt、Sass
后端依赖：Spring Boot WebMVC/JDBC、Druid、JWT、Jackson、IP地址解析、UA解析、SQL Server驱动

graph LR
subgraph "前端依赖"
VUE["Vue 3"]
ROUTER["Vue Router"]
PINIA["Pinia"]
AXIOS["Axios"]
TABLE["stk-table-vue"]
LINT["Oxlint/OxFmt"]
end
subgraph "后端依赖"
SB["Spring Boot"]
JDBC["Spring JDBC"]
DRUID["Druid"]
JWT["JWT"]
JACKSON["Jackson"]
SQL["SQL Server Driver"]
end
VUE --> ROUTER
ROUTER --> PINIA
PINIA --> AXIOS
AXIOS --> TABLE
SB --> JDBC
JDBC --> DRUID
SB --> JWT
SB --> JACKSON
JDBC --> SQL

图表来源

章节来源

性能考虑

前端首屏优化：路由就绪后再挂载应用，减少白屏时间；按需加载FPS监控组件；主题同步在挂载前完成，避免闪烁
表格性能：使用 stk-table-vue 的虚拟滚动与区域选择特性，提升大数据量下的交互体验
后端连接池：合理配置 Druid 初始大小、最大活跃数、空闲回收策略，降低数据库压力
缓存与幂等：对读多写少的接口增加缓存；写接口保证幂等，避免重复提交

[本节为通用指导，无需特定文件引用]

故障排查指南

前端启动失败：main.js 中捕获异常并显示重试按钮；检查网络与路由守卫前置逻辑
后端异常：GlobalExceptionHandler 统一捕获业务与系统异常，返回标准化错误码与信息；查看日志定位问题
配置问题：application.yaml 中的端口、上下文路径、JWT密钥、数据库连接池参数需与环境一致

章节来源

结论

本规范明确了FMS项目在前后端的代码风格、模块组织、质量工具与异常处理策略。遵循本规范可提升代码可读性、可维护性与交付质量。建议在新功能开发中严格对照执行，并通过CI集成自动化检查。

附录

命名约定
- JS/Vue：文件名使用 kebab-case；组件名使用 PascalCase；常量 UPPER_SNAKE_CASE
- Java：包名小写；类名 PascalCase；方法/字段 camelCase；常量 UPPER_SNAKE_CASE
文件组织
- 前端：按功能域划分 views/components/services/stores/utils/styles
- 后端：controller/service/exception/config/database/utils 分层清晰
注释标准
- 公共API与复杂逻辑必须添加JSDoc/Javadoc说明
- 关键分支与边界条件需补充行内注释
质量门禁
- 提交前执行 lint、fmt:check、build、test
- 合并前确保无警告与错误

[本节为通用指导，无需特定文件引用]

14 KiB Raw Blame History Unescape Escape

开发规范

目录

简介

项目结构

核心组件

架构总览

详细组件分析

前端代码风格与质量工具

Vue 组件开发规范

后端 Java 开发规范

数据保存与变更追踪

依赖分析

性能考虑

故障排查指南

结论

附录

14 KiB

Raw Blame History