docs: 迁移 spring-ai 通用文档到 rui-docs
- 添加 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:
@@ -0,0 +1,340 @@
|
||||
# 业务应用模块创建规则
|
||||
|
||||
> 在 `app/` 目录下创建业务模块，按子模块模式拆分。
|
||||
> `app/` 目录整体不提交到 git。
|
||||
|
||||
## 模块结构
|
||||
|
||||
```
|
||||
app/
|
||||
├── pom.xml # 聚合所有业务模块
|
||||
└── rui-{领域}/
|
||||
├── pom.xml # 领域聚合 POM
|
||||
├── rui-{领域}-api/ # [可部署] REST API 服务（有 main Class）
|
||||
├── rui-{领域}-common/ # [库] DTO、枚举、配置、工具
|
||||
├── rui-{领域}-core/ # [库] Mapper、Entity、Service（数据库层）
|
||||
├── rui-{领域}-provider/ # [库] 第三方集成（可选）
|
||||
└── rui-{领域}-task/ # [库] MQ 监听器 + 定时任务（可选）
|
||||
```
|
||||
|
||||
### 三模块（最小配置）
|
||||
|
||||
| 模块 | 类型 | 作用 |
|
||||
|------|------|------|
|
||||
| `-api` | 可部署 | REST 控制器、启动类、application.yml |
|
||||
| `-common` | 库 | DTO、VO、枚举、常量、配置属性 |
|
||||
| `-core` | 库 | Mapper、Entity、Service（MyBatis Plus） |
|
||||
|
||||
### 五模块（含第三方集成和异步任务）
|
||||
|
||||
| 模块 | 类型 | 作用 |
|
||||
|------|------|------|
|
||||
| `-provider` | 库（可选） | 第三方 SDK/API 封装（支付、短信、AI 等） |
|
||||
| `-task` | 库（可选） | MQ 监听器、定时任务、异步处理 |
|
||||
|
||||
## 包命名
|
||||
|
||||
```
|
||||
com.rui.{领域}.api # api 模块
|
||||
com.rui.{领域} # common 模块
|
||||
com.rui.{领域}.core # core 模块
|
||||
com.rui.{领域}.provider # provider 模块
|
||||
com.rui.{领域}.task # task 模块
|
||||
```
|
||||
|
||||
## POM 层级
|
||||
|
||||
```
|
||||
app/pom.xml → parent: rui-parent (不加 relativePath)
|
||||
└── rui-{领域}/pom.xml → parent: rui-app
|
||||
├── rui-{领域}-api/ → parent: rui-{领域}
|
||||
├── rui-{领域}-common/
|
||||
├── rui-{领域}-core/
|
||||
├── rui-{领域}-provider/ （可选）
|
||||
└── rui-{领域}-task/ （可选）
|
||||
```
|
||||
|
||||
> `<relativePath>` 一律不加，Maven 自动从本地仓库查找父 POM。
|
||||
|
||||
## 依赖关系
|
||||
|
||||
```
|
||||
common ——→ rui-common-core
|
||||
core ———→ rui-common-mybatis, rui-common-security, common
|
||||
api ———→ core, rui-common-security, rui-common-web
|
||||
provider → common
|
||||
task ———→ core, common
|
||||
```
|
||||
|
||||
- **框架依赖**（`rui-common-*`）：版本由 `rui-parent` BOM 管理，不加 `<version>`
|
||||
- **内部模块依赖**（`rui-{领域}-*`）：加 `<version>${project.version}</version>`
|
||||
|
||||
## app/pom.xml 模板
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<parent>
|
||||
<groupId>com.rui</groupId>
|
||||
<artifactId>rui-parent</artifactId>
|
||||
<version>1.0.0-SNAPSHOT</version>
|
||||
</parent>
|
||||
|
||||
<artifactId>rui-app</artifactId>
|
||||
<packaging>pom</packaging>
|
||||
|
||||
<name>rui-app</name>
|
||||
<description>睿核科技 — 业务应用模块聚合</description>
|
||||
|
||||
<modules>
|
||||
<module>rui-payment</module>
|
||||
<!-- 新增模块在此添加 -->
|
||||
</modules>
|
||||
</project>
|
||||
```
|
||||
|
||||
## api 模块 POM 模板
|
||||
|
||||
```xml
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>com.alibaba.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>com.alibaba.cloud</groupId>
|
||||
<artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-webmvc</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>com.rui</groupId>
|
||||
<artifactId>rui-{领域}-core</artifactId>
|
||||
<version>${project.version}</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>com.rui</groupId>
|
||||
<artifactId>rui-common-security</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>com.rui</groupId>
|
||||
<artifactId>rui-common-web</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<executions>
|
||||
<execution>
|
||||
<id>repackage</id>
|
||||
<goals><goal>repackage</goal></goals>
|
||||
<configuration><attach>true</attach></configuration>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
```
|
||||
|
||||
## 启动类模板
|
||||
|
||||
```java
|
||||
package com.rui.{领域}.api;
|
||||
|
||||
import com.rui.common.security.annotation.EnableResourceServer;
|
||||
import org.springframework.boot.SpringApplication;
|
||||
import org.springframework.boot.autoconfigure.SpringBootApplication;
|
||||
|
||||
@SpringBootApplication
|
||||
@EnableResourceServer
|
||||
public class {Domain}ApiApplication {
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run({Domain}ApiApplication.class, args);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 日志配置模板
|
||||
|
||||
api 模块需复制日志配置文件：
|
||||
|
||||
```bash
|
||||
cp docs/logback-spring-template.xml \
|
||||
app/rui-{领域}/rui-{领域}-api/src/main/resources/logback-spring.xml
|
||||
```
|
||||
|
||||
- 无需修改，自动读取 `spring.application.name` 作为日志目录名
|
||||
- 按级别分文件（debug / info / warn / error）
|
||||
- 控制台彩色输出，dev 环境显示 DEBUG
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **`app/` 目录加入 `.gitignore`**，业务模块不提交到框架仓库
|
||||
2. api 模块需配置 `@EnableResourceServer`（资源服务器模式）
|
||||
3. **各模块 Bean 通过 `AutoConfiguration.imports` 自动注入**，不在启动类上使用 `scanBasePackages`（参见下方「模块 Bean 注入规范」）
|
||||
4. Mapper 扫描由 `rui-common-mybatis` 统一处理（`@MapperScan("com.rui.**.mapper")`），各模块无需重复配置
|
||||
5. 白名单 URL 通过 `security.oauth2.ignore-urls` 在 Nacos 配置
|
||||
6. 本地开发配置如 `config/application-dev.yml` 也需 gitignore
|
||||
|
||||
## Git 规则
|
||||
|
||||
业务应用模块（`app/` 目录下的模块）使用**独立的 Git 仓库**管理，与框架主仓库完全分离。
|
||||
|
||||
### 仓库初始化
|
||||
|
||||
```bash
|
||||
cd app/rui-{领域}
|
||||
git init
|
||||
git add .
|
||||
git commit -m "feat(init): 初始化{领域}模块"
|
||||
git remote add origin git@gitee.com:pigeon/rui-{领域}.git
|
||||
git push -u origin master
|
||||
```
|
||||
|
||||
### 提交规范
|
||||
|
||||
与框架主仓库一致：
|
||||
|
||||
- **格式**：`type(scope): 中文描述`
|
||||
- **type**：`feat`（新功能）、`fix`（修复）、`docs`（文档）、`refactor`（重构）、`chore`（构建）
|
||||
- **示例**：`feat(payment): 添加支付宝下单接口`
|
||||
|
||||
### 推送规则
|
||||
|
||||
- **本地开发**：修改后自动 `git commit`，但不自动推送
|
||||
- **推送时机**：由开发者手动执行 `git push`，或在完成阶段性开发后统一推送
|
||||
- **自动推送阈值**：当未推送提交数 **超过 10 个** 时，自动推送到远程
|
||||
- **禁止**：将业务模块代码提交到框架主仓库（`app/` 已加入 `.gitignore`）
|
||||
|
||||
### 与框架主仓库的关系
|
||||
|
||||
```
|
||||
spring-ai/ # 框架主仓库（git）
|
||||
├── backend/ # 提交到框架仓库
|
||||
├── docs/ # 提交到框架仓库
|
||||
├── app/ # 不提交到框架仓库（.gitignore）
|
||||
│ └── rui-payment/ # 独立 Git 仓库
|
||||
│ ├── .git/ # 独立的 git 历史
|
||||
│ └── ...
|
||||
```
|
||||
|
||||
## 模块 Bean 注入规范
|
||||
|
||||
### `@SpringBootApplication` 禁止扩大扫描范围
|
||||
|
||||
**API 启动类上的 `@SpringBootApplication` 不得使用 `scanBasePackages` 参数扩大包扫描范围。**
|
||||
|
||||
- 错误示例：`@SpringBootApplication(scanBasePackages = {"com.rui.payment"})`
|
||||
- 正确示例：`@SpringBootApplication`
|
||||
|
||||
启动类应仅扫描自身所在包（`com.rui.{领域}.api`）及其子包。
|
||||
|
||||
### 跨模块 Bean 通过 AutoConfiguration 注入
|
||||
|
||||
其他模块需要暴露给 Spring 容器的 Bean（`@Service`、`@Component`、`@Mapper` 等），**由各模块自行通过 `AutoConfiguration.imports` 注册**。
|
||||
|
||||
**实现方式**：
|
||||
|
||||
1. 在模块中创建自动配置类（通常在 `config` 包下）：
|
||||
|
||||
```java
|
||||
package com.rui.{领域}.core.config;
|
||||
|
||||
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||
import org.springframework.context.annotation.ComponentScan;
|
||||
|
||||
@AutoConfiguration
|
||||
@ComponentScan("com.rui.{领域}.core")
|
||||
public class PaymentCoreAutoConfiguration {
|
||||
}
|
||||
```
|
||||
|
||||
2. 在模块的 `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 中注册：
|
||||
|
||||
```
|
||||
com.rui.{领域}.core.config.PaymentCoreAutoConfiguration
|
||||
```
|
||||
|
||||
**原则**：
|
||||
- 每个可复用模块（core、provider、task）必须有自己的 `AutoConfiguration`
|
||||
- 启动类只需引入依赖，无需关心其他模块的包路径
|
||||
- `rui-common-mybatis` 已通过 `AutoConfiguration.imports` 自动注入并包含 `@MapperScan("com.rui.**.mapper")`，各模块无需重复配置 Mapper 扫描
|
||||
|
||||
## Controller 路径规范
|
||||
|
||||
### URL 格式
|
||||
|
||||
```
|
||||
/{模块}/{功能}/{方法}
|
||||
```
|
||||
|
||||
例如：`/payment/trade/create`、`/order/refund/query`
|
||||
|
||||
### 控制器分类
|
||||
|
||||
| 控制器命名 | 路径 | 认证 | 说明 |
|
||||
|-----------|------|------|------|
|
||||
| `XxxController` | `/{模块}/{功能}/*` | 需认证 | 常规业务接口 |
|
||||
| `XxxEntryController` | `/{模块}/entry/**` | 免认证 | 对外入口（收银台、H5 等） |
|
||||
| `XxxNotifyController` | `/{模块}/notify/**` | 免认证 | 第三方回调（支付、消息等） |
|
||||
| `XxxInnerController` | `/{模块}/inner/**` | 通过 `@Inner` 注解控制 | 内部 Feign 调用 |
|
||||
|
||||
### Nacos 白名单配置
|
||||
|
||||
```yaml
|
||||
# Spring Boot 4 使用 PathPattern，不支持 /**/ 中间通配
|
||||
# 需按模块显式列出白名单路径
|
||||
security:
|
||||
oauth2:
|
||||
ignore-urls:
|
||||
- /payment/entry/**
|
||||
- /payment/notify/**
|
||||
- /user/entry/**
|
||||
- /actuator/**
|
||||
```
|
||||
|
||||
### 示例
|
||||
|
||||
```java
|
||||
// 常规接口 — 需认证
|
||||
@RestController
|
||||
@RequestMapping("/payment/trade")
|
||||
public class PaymentTradeController {
|
||||
@PostMapping("/create")
|
||||
public R<Trade> create(@RequestBody TradeRequest req) { ... }
|
||||
}
|
||||
|
||||
// 对外入口 — 免认证
|
||||
@RestController
|
||||
@RequestMapping("/payment/entry")
|
||||
public class PaymentEntryController {
|
||||
@PostMapping("/alipay")
|
||||
public R<PayResult> alipay(@RequestBody PayRequest req) { ... }
|
||||
}
|
||||
|
||||
// 第三方回调 — 免认证
|
||||
@RestController
|
||||
@RequestMapping("/payment/notify")
|
||||
public class PaymentNotifyController {
|
||||
@PostMapping("/alipay")
|
||||
public String alipayNotify(HttpServletRequest request) { ... }
|
||||
}
|
||||
|
||||
// 内部调用 — @Inner 保护
|
||||
@RestController
|
||||
@RequestMapping("/payment/inner")
|
||||
public class PaymentInnerController {
|
||||
@Inner
|
||||
@GetMapping("/trade/{id}")
|
||||
public Trade getTrade(@PathVariable Long id) { ... }
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user