rui/rui-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 迁移 spring-ai 通用文档到 rui-docs

Browse Source 
- 添加 backend/项目实施规范.md
- 添加 backend/业务应用模块创建规则.md
- 添加 backend/guides/deployment-guide.md
- 添加 frontend/admin-ui-icon-guide.md
- 添加 frontend/admin-ui-status.md
- 更新 README.md 文档索引
This commit is contained in:
pigeon
2026-06-04 09:03:21 +08:00
parent d0771597a6
commit 0666c3ec7b
9 changed files with 2340 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/项目实施规范.md
+440
View File
@@ -0,0 +1,440 @@
# 睿核科技 (rui) — 项目实施规范
> 本文档基于对当前 spring-ai 项目的全面分析，整理项目结构、业务流、现有规范、推荐修改项及缺少的专业结构，供后续项目实施参考。
---
## 一、项目概述
| 项目属性 | 值 |
|---------|-----|
| **项目名称** | spring-ai |
| **项目类型** | Spring Cloud 微服务架构（通用平台框架） |
| **组织方式** | Monorepo（backend + 可扩展前端） |
| **JDK** | 21 |
| **Spring Boot** | 4.0.3 |
| **Spring Cloud** | 2025.1.1 |
| **Alibaba Cloud** | 2025.1.0.0 |
| **MyBatis Plus** | 3.5.16 |
| **包管理** | Maven + flatten-maven-plugin |
| **配置中心** | Nacos |
| **注册中心** | Nacos |
---
## 二、项目架构图
```
┌─────────────────────────────────────────────────────────────┐
│ 客户端（Web/App/小程序） │
└─────────────────────────────┬───────────────────────────────┘
│
┌─────────▼─────────┐
│ rui-gateway │ ← 灰度路由、负载均衡、请求清洗
│ :9300 │
└─────────┬─────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌─────▼─────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ rui-auth │ │rui-service-*│ │ rui-service-*│
│ :9301 │ │ :9302+ │ │ :9302+ │
└─────┬─────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
│ ┌────────▼────────┐ │
│ │ Nacos Config │ │
│ │ Nacos Discovery│ │
│ └─────────────────┘ │
│ │ │
┌─────▼───────────────────▼───────────────────▼─────┐
│ rui-common（通用基础层） │
│ core / web / security / oauth2 / mybatis / feign │
└───────────────────────────────────────────────────┘
```
---
## 三、模块结构与端口分配
### 3.1 核心框架层
| 模块 | 类型 | 端口 | 职责 |
|------|------|------|------|
| **rui-dependencies** | BOM | - | 全局依赖版本管理（Spring Boot/Cloud/Alibaba） |
| **rui-parent** | Parent POM | - | 统一插件配置（Lombok、flatten、Spring Boot Maven） |
### 3.2 通用基础层（rui-common）
| 子模块 | 职责 | 是否已创建 |
|--------|------|-----------|
| rui-common-core | 核心工具类（Result、BaseEntity、TenantContextHolder） | ✅ |
| rui-common-mybatis | MyBatis Plus + Druid + 多租户拦截器 | ✅ |
| rui-common-security | 资源服务器配置、JWT、@Inner 注解、安全切面 | ✅ |
| rui-common-oauth2 | OAuth2 授权服务器、多种认证 Provider | ✅ |
| rui-common-web | BaseController、QueryBuilder、全局异常处理、OpenAPI | ✅ |
| rui-common-feign | Feign 增强（自动注入租户头、自定义 Registrar） | ✅ |
| rui-common-mq | MQ 抽象接口 | ✅ |
| rui-common-mq-redis | Redis 实现 MQ | ✅ |
| rui-common-mq-rabbitmq | RabbitMQ 实现 MQ | ✅ |
| rui-common-authenticator | TOTP 动态码认证 | ✅ |
### 3.3 业务服务层（rui-service）
| 服务名 | 端口 | 状态 | 职责 |
|--------|------|------|------|
| **rui-gateway** | **9300** | ✅ 已创建 | 网关（路由、灰度发布、负载均衡、日志） |
| **rui-auth** | **9301** | ✅ 已创建 | 认证授权中心（薄壳，核心逻辑在 rui-common-oauth2） |
| **rui-service-system** | **9302** | ✅ 已创建 | 系统基础服务（租户、客户端、角色/菜单/字典） |
| **rui-service-user** | **9303** | ✅ 已创建 | 用户中心服务（用户详情、等级体系、登录凭证） |
| rui-service-msg | 9304 | ⏳ 预留 | 消息通知服务（SMS/邮件/站内信/App推送） |
| rui-service-file | 9305 | ⏳ 预留 | 文件存储服务（OSS/本地存储） |
| rui-service-order | 9306 | ⏳ 预留 | 订单服务 |
| rui-service-pay | 9307 | ⏳ 预留 | 支付服务（支付通道、回调、对账） |
| rui-service-search | 9308 | ⏳ 预留 | 搜索服务（Elasticsearch 封装） |
| rui-service-cache | 9309 | ⏳ 预留 | 缓存服务（Redis 分布式锁等封装） |
| rui-service-log | 9310 | ⏳ 预留 | 日志收集服务（ELK 集成） |
| rui-service-monitor | 9311 | ⏳ 预留 | 监控告警服务（Micrometer/Prometheus） |
---
## 四、核心业务流
### 4.1 认证授权流程（OAuth2）
```
┌─────────────┐ POST /auth/oauth2/token ┌──────────────┐
│ 客户端 │ ────────────────────────────────> │ rui-auth │
│ (前端/App) │ │ :9301 │
└─────────────┘ └──────┬───────┘
│
1. 获取客户端信息 │
(ClientInnerController)
:9302 /system/inner/client/*
│
2. 获取用户信息 │
(UserInnerController)
:9303 /user/inner/auth/*
│
▼
3. 生成 JWT Token
(RuiTokenCustomizer)
存储到 Redis
│
▼
┌─────────────┐ 返回 Token ┌──────────────┐
│ 客户端 │ <────────────────── │ rui-auth │
└─────────────┘ └──────────────┘
```
**支持的认证方式**：
- `password` — 用户名密码
- `sms` — 短信验证码
- `weixin` — 微信登录
- `alipay` — 支付宝登录
- `client_credentials` — 客户端凭证
- `refresh_token` — 刷新令牌
### 4.2 资源访问流程
```
┌─────────────┐ 携带 Token ┌──────────────┐ 路由 ┌──────────────┐
│ 客户端 │ ──────────────────> │ rui-gateway │ ───────────> │ 业务服务 │
└─────────────┘ │ :9300 │ │ :9302/9303+ │
└──────┬───────┘ └──────┬───────┘
│ │
灰度路由决策 资源服务器校验
(权重/用户/IP/Header) (JWT 验证)
│ │
内部请求头清洗 @Inner 校验
(INTERNAL_REQUEST) (SecurityInnerAspect)
```
### 4.3 内部服务调用流程（Feign）
```
业务服务 A 业务服务 B
│ │
│ Feign 调用 │
│ ──────────────────────────────────────────> │
│ │
│ 自动注入 Header │
│ - Authorization (OAuth2 Token) │
│ - INTERNAL_REQUEST: INTERNAL │
│ - X-Tenant-Id (租户ID) │
│ │
│ 通过 @Inner 注解校验 │
│ (SecurityInnerAspect) │
│ │
│ 返回 Result<T> │
│ <────────────────────────────────────────── │
│ │
│ Remote 服务层解包 │
│ (转换为具体类型) │
```
---
## 五、现有规范清单
### 5.1 编码规范
| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 文档语言 | 所有文档、注释必须使用中文 | ✅ 已规则化（AGENTS.md） |
| 2 | 标识符 | 类名/方法名/变量名使用英文 | ✅ 已规则化 |
| 3 | JDK | 21（强制） | ✅ 已规则化 |
| 4 | Lombok | 强制使用，禁止手写 getter/setter/builder | ✅ 已规则化 |
| 5 | 实体类 | 必须继承 BaseEntity，加 @EqualsAndHashCode(callSuper = true) | ✅ 已规则化 |
| 6 | Service 注入 | 构造器注入（private final + 构造器） | ✅ 已规则化 |
| 7 | 类名前缀 | 不加 Rui 前缀，除非与框架类冲突 | ✅ 已规则化 |
| 8 | 版本管理 | 统一使用 ${revision} + flatten-maven-plugin | ✅ 已规则化 |
| 9 | 代码注释 | 所有代码注释使用中文 | ❌ **建议加入规则** |
### 5.2 Feign 规范
| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | contextId | 必须使用，隔离 Bean 命名空间 | ✅ 已规则化 |
| 2 | 服务名 | value = "${feign.providers.xxx:默认名}" 外部化 | ✅ 已规则化 |
| 3 | 返回值 | Inner API 统一返回 Result<T> | ✅ 已规则化 |
| 4 | 注册方式 | META-INF/spring.factories 注册 CloudFeignAutoConfiguration | ✅ 已规则化 |
| 5 | 调用头 | @Headers("INTERNAL_REQUEST: INTERNAL") 自动注入 | ✅ 已规则化 |
| 6 | 解包方式 | Remote 服务层解包并转换 | ✅ 已规则化 |
| 7 | 降级处理 | 禁止使用 fallback/fallbackFactory，Remote 层 try-catch | ✅ 已规则化 |
### 5.3 URL 路由规范
| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 格式 | /{模块}/{目录层级...}/{功能}/{方法} | ✅ 已规则化 |
| 2 | 模块位置 | 模块标识在最前（方便网关路由） | ✅ 已规则化 |
| 3 | 内部标识 | 内部接口统一使用 /inner | ✅ 已规则化 |
| 4 | 网关配置 | 网关只需配置 /{模块}/** | ✅ 已规则化 |
### 5.4 Controller 分类规范
| 控制器命名 | 路径前缀 | 认证要求 | 用途 | 是否加入规则 |
|-----------|---------|---------|------|------------|
| XxxController | /{模块}/{功能}/** | 需认证 | 常规业务接口 | ✅ 已规则化 |
| XxxEntryController | /{模块}/entry/** | 免认证 | 对外入口（注册、登录前） | ✅ 已规则化 |
| XxxNotifyController | /{模块}/notify/** | 免认证 | 第三方回调（支付、Webhook） | ✅ 已规则化 |
| XxxInnerController | /{模块}/inner/** | @Inner 控制 | 内部 Feign 调用 | ✅ 已规则化 |
### 5.5 数据库规范
| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 实体基类 | 继承 BaseEntity（含 id, createTime, updateTime, tenantId, deleted） | ✅ 已实现 |
| 2 | 多租户 | 使用 MyBatis Plus 多租户拦截器（TenantLineInnerInterceptor） | ✅ 已实现 |
| 3 | 逻辑删除 | 使用 @TableLogic 注解，字段名 deleted | ✅ 已实现 |
| 4 | 自动填充 | 使用 MetaObjectHandler 自动填充创建/更新时间 | ✅ 已实现 |
| 5 | 表命名 | 统一前缀 rui_{模块}_{表名}（如 rui_user_credential） | ⚠️ **建议规则化** |
| 6 | 字段命名 | 下划线命名，主键 id，租户 tenant_id | ⚠️ **建议规则化** |
| 7 | SQL 防注入 | 启用 BlockAttackInnerInterceptor（防全表更新/删除） | ✅ 已实现 |
### 5.6 Git 规范
| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 自动提交 | 每次修改后自动 git commit，不推送 | ✅ 已规则化 |
| 2 | 推送时机 | 由用户提示或累积多次提交后统一推送 | ✅ 已规则化 |
| 3 | 忽略目录 | app/、config/ 加入 .gitignore | ✅ 已规则化 |
| 4 | 提交信息 | 使用中文描述，格式：type(scope): 描述 | ❌ **建议加入规则** |
| 5 | 分支策略 | main 为主分支，功能分支开发 | ❌ **建议加入规则** |
### 5.7 Maven 规范
| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 版本管理 | ${revision} + flatten-maven-plugin | ✅ 已规则化 |
| 2 | 版本发布 | mvn deploy -Drevision=x.x.x | ✅ 已规则化 |
| 3 | 正式仓库 | https://maven.dev.vifo.cc/repository/maven-releases/ | ✅ 已规则化 |
| 4 | 快照仓库 | https://maven.dev.vifo.cc/repository/maven-snapshots/ | ✅ 已规则化 |
| 5 | 依赖引入 | 版本在 rui-dependencies 中统一管理 | ✅ 已规则化 |
| 6 | relativePath | 子模块必须指定 relativePath 指向 rui-parent | ✅ 已实现 |
### 5.8 配置中心规范（Nacos）
| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 配置拆分 | 每个服务独立 Data ID（rui-{服务名}.yaml） | ✅ 已实现 |
| 2 | 共享配置 | rui-common.yaml 存放全局配置 | ✅ 已实现 |
| 3 | 数据库配置 | rui-data.yaml 存放 MySQL/Druid/MyBatis 配置 | ✅ 已实现 |
| 4 | 端口配置 | 每个服务配置在各自 Nacos 配置文件中 | ✅ 已实现 |
| 5 | 灰度配置 | 在 rui-gateway.yaml 中配置 grayscale.rules | ✅ 已实现 |
| 6 | 配置推送 | 使用 push-nacos-config.sh 统一推送 | ✅ 已实现 |
---
## 六、推荐修改项
### 6.1 高优先级（建议立即修改）
| # | 修改项 | 当前问题 | 修改建议 |
|---|--------|---------|---------|
| 1 | **rui-auth 过于单薄** | 仅 2 个 Java 文件（启动类 + 配置类） | 将 AuthServerConfig 下沉到 rui-common-oauth2，或补充 Token 管理、Session 管理等接口 |
| 2 | **rui-service-system 不完整** | 仅 4 个文件，无完整 Controller/Service/Mapper | 尽快补齐租户管理、菜单/角色/字典的 CRUD 接口 |
| 3 | **Mapper XML 缺失** | 全局未找到 .xml Mapper 文件 | 确认是否全注解 SQL（当前 JdbcTemplate 直接写 SQL），建议补充 MyBatis Plus 的 Mapper 接口 |
| 4 | **rui-dependencies 中声明了未存在的模块** | rui-common-mq-mqtt 在 BOM 中声明但目录不存在 | 删除该声明或创建对应模块 |
| 5 | **自动配置注册方式不统一** | 部分模块使用 spring.factories，部分未注册 | 统一使用 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports |
| 6 | **BaseController 字段反射注入** | bindCurrentUser 使用反射调用 setter | 改用 MetaObjectHandler 统一处理，或使用构造器注入 |
| 7 | **文档术语不统一** | docs/spring-rui 代码分析报告.md 提到 R<T>，实际代码使用 Result<T> | 统一术语，删除或更新旧文档 |
### 6.2 中优先级（近期完善）
| # | 修改项 | 当前问题 | 修改建议 |
|---|--------|---------|---------|
| 1 | **单元测试缺失** | 未见到 src/test/java 目录 | 补充 JUnit 5 + Mockito 测试框架，编写基础单元测试 |
| 2 | **日志追踪缺失** | 无 TraceID 链路追踪 | 引入 MDC + TraceID 过滤器，实现请求全链路追踪 |
| 3 | **QueryBuilder 区间查询弱** | putBetween 仅支持字符串拼接 | 支持日期/数字区间查询，前端传递 JSON 格式查询条件 |
| 4 | **MybatisProperties 利用率低** | 已定义配置但 TenantHandler 仍部分硬编码 | 完全配置驱动，租户字段名、逻辑删除字段名均可配置 |
| 5 | **灰度负载均衡缺少降级计数** | 灰度实例不可用时直接回退稳定实例 | 增加灰度实例健康检查，记录降级次数和比例 |
| 6 | **app/ 目录验证** | .gitignored，当前为空 | 按 docs/业务应用模块创建规则.md 创建示例模块（如 rui-payment），验证规范可行性 |
### 6.3 低优先级（按需实施）
| # | 修改项 | 当前问题 | 修改建议 |
|---|--------|---------|---------|
| 1 | **分布式链路追踪** | 无 SkyWalking / Micrometer Tracing | 引入 Micrometer Tracing + Brave 实现链路追踪 |
| 2 | **监控告警模块** | Nacos 有配置占位，backend 无代码 | 集成 Micrometer + Prometheus，或接入 Sentinel Dashboard |
| 3 | **工具类补齐** | 部分通用工具可能缺失 | 移植 SpringUtil、JsonUtil、IdWorker 等工具类到 rui-common-core |
| 4 | **缓存抽象层** | Redis 使用直接，无统一缓存接口 | 在 rui-common-core 中定义 CacheManager 接口，支持多级缓存 |
| 5 | **限流降级** | 缺少统一限流策略 | 在网关层集成 Sentinel，或基于 Redis 实现分布式限流 |
---
## 七、缺少的专业结构
### 7.1 必须补充的结构
| 结构 | 缺失模块 | 重要性 | 实施建议 |
|------|---------|--------|---------|
| **完整的 rui-service-system** | rui-service-system | 🔴 高 | 补充 SystemTenant、SystemMenu、SystemRole、SystemDict、SystemConfig 的 Entity、Mapper、Service、Controller |
| **Mapper 接口层** | rui-service-user、rui-service-system | 🔴 高 | 为所有 Entity 创建 Mapper 接口，继承 BaseMapper，使用 @Mapper 注解 |
| **单元测试目录** | 所有模块 | 🔴 高 | 创建 src/test/java 和 src/test/resources，编写至少一个示例测试类 |
| **自动配置注册** | rui-common-* 模块 | 🟡 中 | 每个模块创建 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports |
| **业务应用示例模块** | app/ 目录 | 🟡 中 | 创建 rui-payment-api/common/core/provider/task 示例，验证业务模块创建规则 |
### 7.2 建议补充的结构
| 结构 | 说明 | 重要性 | 实施建议 |
|------|------|--------|---------|
| **API 文档自动生成** | OpenAPI/SpringDoc 已集成，但未统一配置 | 🟡 中 | 统一配置 API 文档标题、版本、鉴权方式，生成在线文档 |
| **数据库变更管理** | 缺少 Flyway/Liquibase | 🟡 中 | 引入 Flyway 管理数据库版本，脚本放在 src/main/resources/db/migration/ |
| **代码质量检查** | 缺少 Checkstyle/SpotBugs | 🟢 低 | 配置 Checkstyle 规则，集成到 Maven 构建流程 |
| **Docker 支持** | 缺少 Dockerfile / docker-compose | 🟢 低 | 为每个服务创建 Dockerfile，提供 docker-compose.yml 本地开发环境 |
| **Kubernetes 配置** | 缺少 K8s YAML | 🟢 低 | 提供基础的 Deployment、Service、ConfigMap 模板 |
| **SonarQube 集成** | 缺少代码质量扫描 | 🟢 低 | 配置 SonarQube 扫描，设置质量门禁 |
---
## 八、新规范建议（需加入 AGENTS.md）
### 8.1 建议立即加入的规则
```markdown
## 数据库规范
- **表命名**: 统一前缀 `rui_{模块}_{表名}`，如 `rui_user_credential`
- **字段命名**: 下划线命名法，主键 `id`，租户 `tenant_id`，逻辑删除 `deleted`
- **实体类**: 必须继承 `BaseEntity`，使用 `@TableName` 指定表名
- **Mapper**: 必须继承 `BaseMapper<Entity>`，使用 `@Mapper` 注解
- **SQL**: 优先使用 MyBatis Plus 条件构造器，复杂 SQL 使用 XML 或 @Select
## Git 提交规范
- **格式**: `type(scope): 中文描述`
- **type**: feat/fix/docs/style/refactor/test/chore
- **示例**: `feat(user): 添加用户等级查询接口`
- **要求**: 每次提交原子性，不混合多个功能修改
## 代码注释规范
- **语言**: 所有注释使用中文
- **类注释**: 说明类的作用、作者、创建日期
- **方法注释**: 说明方法用途、参数、返回值
- **复杂逻辑**: 必须添加行内注释说明业务意图
## 接口版本规范
- **REST API**: 对外接口建议添加版本前缀，如 `/v1/user/info`
- **兼容性**: 重大变更升级版本号，保持向后兼容
```
### 8.2 建议后续加入的规则
```markdown
## 测试规范
- **覆盖率**: 核心业务逻辑覆盖率不低于 80%
- **测试类型**: 单元测试（JUnit 5 + Mockito）+ 集成测试（@SpringBootTest）
- **命名**: 测试类以 Test 结尾，测试方法以 should_ 开头
## 日志规范
- **级别**: DEBUG（开发调试）、INFO（业务流水）、WARN（可恢复异常）、ERROR（严重错误）
- **格式**: 包含 TraceID、用户ID、操作类型、耗时
- **禁止**: 禁止输出密码、Token、身份证号等敏感信息
## 异常处理规范
- **自定义异常**: 业务异常统一继承 BizException
- **错误码**: 统一错误码规范，按模块分配区间
- **全局处理**: 通过 GlobalExceptionHandler 统一处理，不遗漏异常
```
---
## 九、Nacos 配置清单（已推送）
| Data ID | 服务 | 端口 | 状态 |
|---------|------|------|------|
| rui-common.yaml | 全局共享 | - | ✅ |
| rui-data.yaml | DB 模块共享 | - | ✅ |
| rui-gateway.yaml | 网关 | 9300 | ✅ |
| rui-auth.yaml | 认证中心 | 9301 | ✅ |
| rui-service-system.yaml | 系统服务 | 9302 | ✅ |
| rui-service-user.yaml | 用户服务 | 9303 | ✅ |
| rui-service-msg.yaml | 消息服务 | 9304 | ⏳ 预留 |
| rui-service-file.yaml | 文件服务 | 9305 | ⏳ 预留 |
| rui-service-order.yaml | 订单服务 | 9306 | ⏳ 预留 |
| rui-service-pay.yaml | 支付服务 | 9307 | ⏳ 预留 |
| rui-service-search.yaml | 搜索服务 | 9308 | ⏳ 预留 |
| rui-service-cache.yaml | 缓存服务 | 9309 | ⏳ 预留 |
| rui-service-log.yaml | 日志服务 | 9310 | ⏳ 预留 |
| rui-service-monitor.yaml | 监控服务 | 9311 | ⏳ 预留 |
---
## 十、后续实施路线图
### Phase 1：基础完善（1-2 周）
1. ✅ 补齐 rui-service-system 的完整 CRUD
2. ✅ 为所有 Entity 补充 Mapper 接口
3. ✅ 统一自动配置注册方式
4. ✅ 补充单元测试基类和示例
5. ✅ 创建 app/ 目录示例模块
### Phase 2：功能增强（2-4 周）
1. 引入日志链路追踪（TraceID）
2. 完善 QueryBuilder 区间查询
3. 补充 API 文档自动生成配置
4. 引入 Flyway 数据库版本管理
5. 完善灰度发布的降级策略
### Phase 3：生产就绪（4-6 周）
1. 引入分布式链路追踪（SkyWalking/Micrometer）
2. 完善监控告警模块
3. 配置 Docker 和 docker-compose
4. 集成 SonarQube 代码质量检查
5. 编写完整的运维部署文档
---
> **文档版本**: v1.0
> **创建日期**: 2026-05-28
> **适用范围**: spring-ai 项目及后续同类项目
> **维护方式**: 随项目实施迭代更新