# henfon-cloud

**Repository Path**: henfon/henfon-cloud

## Basic Information

- **Project Name**: henfon-cloud
- **Description**: 后端脚手架微服务版
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-23
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Henfon Cloud 后端微服务脚手架

基于 Spring Boot 3 + Spring Cloud + Spring Cloud Alibaba 的后端脚手架，当前已落地系统管理能力（用户、角色、菜单、字典、配置、日志）并可直接与 `henfon-cloud-vue` 联调。

## 1. 项目概览

当前仓库是一个 Maven 多模块工程，核心由以下服务组成：

- `henfon-modules-system`：系统服务（端口 `8082`）
- `henfon-gateway`：网关服务（端口 `8080`）

运行链路：

- 前端直连模式：`henfon-cloud-vue -> henfon-system(8082)`
- 网关模式：`henfon-cloud-vue -> henfon-gateway(8080/api) -> henfon-system`

## 2. 技术栈与版本

- JDK 17
- Maven 3.8+
- Spring Boot 3.2.5
- Spring Cloud 2023.0.2
- Spring Cloud Alibaba 2023.0.1.0
- MyBatis-Plus 3.5.5
- Sa-Token 1.37.0
- MySQL 8.x
- Redis 6.x/7.x
- Nacos 2.x

## 3. 模块说明

```text
henfon-cloud
├── henfon-common/           # 公共能力模块（core/db/redis/security/oss/map/pay/ai/mq）
├── henfon-api/              # API 契约模块（当前含 henfon-api-system）
├── henfon-gateway/          # 网关服务（Spring Cloud Gateway）
├── henfon-modules/
│   ├── henfon-modules-system/   # 系统服务（当前主要业务服务）
│   └── henfon-modules-business/ # 业务 demo 服务（AI / Map / MQ / OSS / Pay）
├── nacos-config/            # Nacos 配置模板
├── sql/                     # 数据库初始化脚本
└── logs/                    # 本地日志目录（已忽略日志文件）
```

## 4. 首次启动（从 0 到可登录）

### 4.1 准备中间件

先启动以下依赖：

1. MySQL（默认连接：`localhost:3306`）
2. Redis（默认连接：`localhost:6379`）
3. Nacos（默认连接：`localhost:8848`）

### 4.2 初始化数据库

1. 创建数据库：`henfon_cloud`
2. 执行脚本：`sql/init.sql`

脚本内已包含：

- 表结构（用户、角色、菜单、字典、配置、日志）
- 初始化管理员账号 `admin/123456`
- 初始化系统菜单和角色权限

### 4.3 导入 Nacos 配置

在 Nacos 中创建命名空间（建议名称和 ID 都用 `dev`），然后导入以下 Data ID（Group 均为 `DEFAULT_GROUP`）：

1. `henfon-system.yaml`
2. `henfon-gateway.yaml`
3. `henfon-redis.yaml`
4. `henfon-business.yaml`

配置文件路径：

- `nacos-config/henfon-system.yaml`
- `nacos-config/henfon-gateway.yaml`
- `nacos-config/henfon-redis.yaml`
- `nacos-config/henfon-business.yaml`

### 4.4 启动系统服务（必需）

在仓库根目录执行：

```bash
mvn -pl henfon-modules/henfon-modules-system -am spring-boot:run
```

或进入模块目录执行：

```bash
cd henfon-modules/henfon-modules-system
mvn spring-boot:run
```

启动成功后，系统服务地址：

- `http://localhost:8082`

### 4.5 启动 demo 业务服务（可选）

在仓库根目录执行：

```bash
mvn -pl henfon-modules/henfon-modules-business -am spring-boot:run
```

或进入模块目录执行：

```bash
cd henfon-modules/henfon-modules-business
mvn spring-boot:run
```

启动成功后，demo 业务服务地址：

- `http://localhost:8083`

### 4.6 启动网关服务（可选）

在仓库根目录执行：

```bash
mvn -pl henfon-gateway -am spring-boot:run
```

或进入网关目录执行：

```bash
cd henfon-gateway
mvn spring-boot:run
```

启动成功后，网关地址：

- `http://localhost:8080`

## 5. 与前端联调

前端仓库：`../henfon-cloud-vue`

### 5.1 推荐入门：直连系统服务

前端 `.env.test` 保持：

```env
VITE_SERVICE_BASE_URL=http://localhost:8082
```

此模式下不依赖网关，先跑通业务最快。

### 5.2 完整链路：走网关

前端 `.env.test` 改为：

```env
VITE_SERVICE_BASE_URL=http://localhost:8080/api
```

并确保网关服务已启动。

## 6. 关键配置说明

### 6.1 Nacos 加载方式

- `henfon-modules-system` 会加载：
  - `henfon-system.yaml`
  - `henfon-redis.yaml`
- `henfon-gateway` 会加载：
  - `henfon-gateway.yaml`
  - `henfon-redis.yaml`
- `henfon-modules-business` 会加载：
  - `henfon-business.yaml`

### 6.2 数据库字符集注意事项

JDBC 参数请使用：

```text
characterEncoding=UTF-8
```

不要写成 `characterEncoding=utf8mb4`，否则可能触发：

- `Unsupported character encoding 'utf8mb4'`

### 6.3 网关路由前缀

当前网关转发规则：

- `/api/system/**` -> `henfon-system`
- `/api/auth/**` -> `henfon-system`
- `/api/route/**` -> `henfon-system`
- `/api/business/**` -> `henfon-business`
- `/api/demo/**` -> `henfon-business`

## 7. 常用命令

### 7.1 编译全部模块

```bash
mvn clean install -DskipTests
```

### 7.2 仅编译系统服务及依赖

```bash
mvn -pl henfon-modules/henfon-modules-system -am -DskipTests compile
```

### 7.3 仅编译网关及依赖

```bash
mvn -pl henfon-gateway -am -DskipTests compile
```

## 8. 日志规范

项目根目录已建立 `logs/` 目录用于本地运行日志，例如：

- `logs/gateway-run.out.log`
- `logs/gateway-run.err.log`

`.gitignore` 已忽略日志内容，仅保留 `logs/.gitkeep` 目录占位文件。

## 9. 常见问题排查

### 9.1 登录或菜单接口 500

优先检查：

1. MySQL、Redis、Nacos 是否都已启动
2. Nacos 是否导入了 `henfon-system.yaml` 和 `henfon-redis.yaml`
3. 数据库 `henfon_cloud` 是否执行了 `sql/init.sql`

### 9.2 前端报 405 Method Not Allowed

通常是前端请求方法或路径与后端 Controller 不一致（如 `/list`、`PUT /status/{id}`）。  
请按后端控制器映射对齐接口定义。

### 9.3 前端一直转圈

重点检查以下接口是否正常返回：

1. `/auth/login`
2. `/route/getUserRoutes`
3. `/route/getConstantRoutes`

## 10. 当前状态说明

- `henfon-modules-system`：可直接运行并支撑后台管理核心功能
- `henfon-gateway`：可直接运行并提供统一入口
- `henfon-modules-business`：可运行的 demo 业务服务，提供 AI / Map / MQ / OSS / Pay 演示接口

## 11. 新增微服务指南（以订单服务为例）

以下示例以新增 `henfon-modules-order`（订单服务）为目标。

### 11.1 新建模块目录与聚合声明

1. 在 `henfon-modules/` 下新建目录：`henfon-modules-order`
2. 新建标准 Maven 结构：
   - `src/main/java`
   - `src/main/resources`
   - `pom.xml`
3. 在 `henfon-modules/pom.xml` 的 `<modules>` 中加入：

```xml
<module>henfon-modules-order</module>
```

### 11.2 配置模块 `pom.xml`

`henfon-modules-order/pom.xml` 建议与 `henfon-modules-system` 保持一致风格，最小依赖建议：

- `henfon-common-core`
- `henfon-common-db`
- `henfon-common-redis`（如需 Redis）
- `spring-cloud-starter-alibaba-nacos-discovery`
- `spring-cloud-starter-alibaba-nacos-config`
- `spring-cloud-starter-loadbalancer`
- `spring-boot-starter-web`
- `mysql-connector-j`（runtime）

### 11.3 新建启动类

示例：

```java
@SpringBootApplication
@EnableDiscoveryClient
public class OrderApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderApplication.class, args);
    }
}
```

### 11.4 配置本地资源文件

在 `henfon-modules-order/src/main/resources/` 下新增：

1. `bootstrap.yml`
   - `spring.application.name: henfon-order`
   - Nacos `server-addr: 127.0.0.1:8848`
   - Nacos `namespace: dev`
2. `application.yml`
   - `spring.config.import` 引入：
     - `optional:nacos:henfon-order.yaml`
     - `optional:nacos:henfon-redis.yaml`

### 11.5 新增 Nacos 配置

在 `nacos-config/` 下新增 `henfon-order.yaml`，最少包含：

- `server.port`（例如 `8083`）
- `spring.application.name: henfon-order`
- `spring.datasource.*`
- `spring.cloud.nacos.discovery.*`

然后在 Nacos `dev` 命名空间发布 `henfon-order.yaml`。

### 11.6 网关增加路由转发

在 `henfon-gateway.yaml` 增加路由：

```yaml
- id: henfon-order
  uri: lb://henfon-order
  predicates:
    - Path=/api/order/**
  filters:
    - StripPrefix=1
```

发布到 Nacos 后，网关即可转发 `/api/order/**` 请求。

### 11.7 API 契约模块（推荐）

建议在 `henfon-api/` 新增 `henfon-api-order`：

1. 放 DTO / VO / Feign 接口
2. 订单服务与调用方都依赖该模块
3. 避免服务间直接依赖实现代码

### 11.8 数据库脚本

建议新增脚本（例如 `sql/order-init.sql`）：

1. 建 `order_*` 相关表
2. 与系统表脚本分离，便于版本管理和独立部署

### 11.9 启动与验证

1. 启动订单服务：

```bash
mvn -pl henfon-modules/henfon-modules-order -am spring-boot:run
```

2. 检查 Nacos 服务列表是否出现 `henfon-order`
3. 通过网关验证接口：
   - `http://localhost:8080/api/order/**`