# mole-modules-example

**Repository Path**: mole-platform/mole-modules-example

## Basic Information

- **Project Name**: mole-modules-example
- **Description**: 示例工程
基于mole-platform基础框架和用户中心mole-modules-user进行搭建。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-15
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mole 示例工程

这是一个基于 Mole 平台的业务系统示例工程，重点展示如何在 Mole 生态中构建和开发业务模块。项目基于 Mole-User 用户中心（使用 Spring Security OAuth2 作为认证中心）进行鉴权，示例工程作为资源中心通过 OAuth2 协议与认证中心进行通信，专注于业务逻辑的实现，提供了完整的 CRUD 操作示例和业务方法演示。

## 项目特性

- **微服务架构**：基于 Spring Cloud Alibaba 构建的微服务应用
- **统一鉴权**：集成 Mole-User 用户中心（基于 Spring Security OAuth2）进行身份认证和权限控制
- **OAuth2 资源中心**：示例工程作为 OAuth2 资源服务器，通过 Token 验证请求合法性
- **ORM 框架**：使用 MyBatis-Plus 简化数据库操作
- **服务治理**：通过 Nacos 实现服务注册与发现
- **分布式配置**：使用 Nacos 配置中心管理多环境配置
- **分页插件**：集成 PageHelper 实现高效分页查询
- **数据库迁移**：使用 Flyway 进行数据库版本控制
- **缓存支持**：基于 Spring Cache 实现方法级缓存
- **API 文档**：使用 Swagger/OpenAPI 自动生成 API 文档
- **代码简化**：使用 Lombok 减少样板代码

## 技术栈

- **Spring Boot 2.x** - 应用框架
- **Spring Cloud Alibaba** - 微服务全家桶
- **Spring Security OAuth2** - 认证与授权框架
- **MyBatis-Plus** - ORM 框架
- **Nacos** - 服务注册与配置中心
- **Redis** - Token 存储与缓存
- **PageHelper** - 分页插件
- **Flyway** - 数据库迁移工具
- **Lombok** - 代码简化工具
- **Swagger/OpenAPI** - API 文档工具

## 认证与授权架构

### OAuth2 架构

本项目采用 OAuth2 认证架构：

1. **认证中心（Authorization Server）**：由 Mole-User 用户中心提供
   - 使用 Spring Security OAuth2 实现
   - 负责用户身份认证
   - 发放访问令牌（Access Token）
   - 支持多种授权模式（密码模式、刷新令牌模式等）

2. **资源中心（Resource Server）**：本示例工程
   - 集成 Spring Security OAuth2 资源服务器功能
   - 通过 `@EnableResourceServer` 注解启用
   - 验证请求中的 Access Token 合法性
   - 根据 Token 中的权限信息控制资源访问

### 认证流程

```
用户 → 前端应用 → 认证中心（Mole-User）→ 获取 Access Token
         ↓
前端应用 → 资源中心（示例工程）→ 验证 Token → 响应资源
```

### Token 验证

- 资源中心通过认证中心验证 Token 合法性
- 使用 Redis 存储 Token，支持 Token 的生成、验证和过期管理
- Token 包含用户信息、权限范围和有效期

## 快速开始

### 环境要求

- JDK 1.8+
- Maven 3.6+
- Nacos 服务端（用于服务注册与配置）
- Mole-User 用户中心服务（作为 OAuth2 认证中心）
- Redis 服务端（用于 Token 存储和缓存）

### 启动项目

```bash
# 克隆项目
git clone <项目地址>

# 进入项目目录
cd mole-modules-example

# 编译项目
mvn compile

# 运行项目
mvn spring-boot:run
```

### 访问项目

- **应用地址**：http://localhost:8080
- **API 文档**：http://localhost:8080/doc.html

### 访问受保护的 API

由于示例工程是 OAuth2 资源中心，访问受保护的 API 需要在请求头中添加 Access Token：

```bash
# 使用 curl 访问示例
curl -H "Authorization: Bearer <your-access-token>" http://localhost:8080/example/1
```

### 获取 Access Token

可以通过 Mole-User 用户中心的 OAuth2 端点获取 Access Token。例如，使用密码模式：

```bash
curl -X POST "http://<mole-user-address>/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "client-id:client-secret" \
  -d "grant_type=password&username=<username>&password=<password>"
```

## 项目结构

```
src/main/java/com/platform/mole/
├── MoleModulesExampleApplication.java  # 应用入口（启用资源服务器）
├── controller/                         # 控制器层
│   ├── ExampleController.java         # 示例表API
│   └── PersonController.java          # 人员表API
├── entity/                             # 实体层
│   ├── Example.java                   # 示例表实体（含加密字段）
│   └── Person.java                    # 人员表实体（含业务方法）
├── mapper/                             # 数据访问层
│   ├── ExampleMapper.java
│   └── PersonMapper.java
└── service/                            # 业务逻辑层
    ├── IExampleService.java
    ├── IPersonService.java
    └── impl/
        ├── ExampleServiceImpl.java
        └── PersonServiceImpl.java
```

### 应用入口说明

```java
@EnableResourceServer  // 启用 OAuth2 资源服务器功能
@SpringBootApplication
@EnableCaching
@Slf4j
public class MoleModulesExampleApplication {
    // ...
}
```

`@EnableResourceServer` 注解是 OAuth2 资源中心的核心配置，它：
1. 自动配置 Spring Security 以拦截请求并验证 Access Token
2. 提供默认的安全配置，保护所有 API 端点
3. 支持通过配置自定义安全规则

## 核心业务模块

### 示例表管理 (Example)

提供示例数据的 CRUD 操作，包含：

- **分页查询**：支持搜索和排序功能
- **单条查询**：通过 ID 查询数据（支持缓存）
- **保存/更新**：支持新增和修改操作
- **删除**：支持逻辑删除（保留数据痕迹）

**API 接口**：
- `POST /example/list` - 分页查询
- `GET /example/{id}` - 获取单条数据
- `POST /example/save` - 保存或更新
- `DELETE /example/{id}` - 删除数据


## 数据库设计

### 示例表 (example)

| 字段名        | 类型          | 描述          |
|--------------|--------------|--------------|
| id           | BIGINT       | 主键ID        |
| name         | VARCHAR      | 用户名（加密）|
| revision     | INTEGER      | 乐观锁版本号  |
| created_by   | VARCHAR      | 创建人        |
| created_time | DATETIME     | 创建时间      |
| updated_by   | VARCHAR      | 更新人        |
| updated_time | DATETIME     | 更新时间      |
| active       | BOOLEAN      | 是否有效      |


## 开发规范

### MyBatis-Plus 使用

1. 实体类需使用以下注解：
   - `@TableName` - 表名映射
   - `@TableId` - 主键标识
   - `@TableField` - 字段映射
   - `@Version` - 乐观锁版本号

2. Mapper 接口需继承 `BaseMapper<T>`

3. 服务类需继承 `ServiceImpl<Mapper, Entity>` 或实现 `IService<T>`

### 缓存使用

1. 在接口方法上使用注解：
   - `@Cacheable` - 缓存查询结果
   - `@CacheEvict` - 清除缓存

2. 缓存配置在 Nacos 配置中心管理

### 数据库迁移

1. 新增 SQL 脚本放在 `src/main/resources/db/migration/` 目录
2. 命名格式：`V{版本号}__{描述}.sql`
3. 示例：`V1.0.0__init_table.sql`

### API 开发

1. 控制器类使用注解：
   - `@RestController` - 声明 REST 控制器
   - `@RequestMapping` - 基础路由
   - `@Api` - Swagger 文档说明

2. 方法使用注解：
   - `@ApiOperation` - 接口说明
   - `@GetMapping`/`@PostMapping`/`@DeleteMapping` - HTTP 方法

## 常用命令

### 构建与编译

```bash
# 编译项目
mvn compile

# 打包项目（跳过测试）
mvn package -DskipTests

# 清理并重新构建
mvn clean install -DskipTests
```

## 配置说明

### 环境配置

项目使用 Maven 配置文件管理多环境（pom.xml）：

- **dev**（默认）：开发环境
  - Nacos 地址：X.X.X.X:8848
  - Docker 镜像仓库：X.X.X.X:8085

### 资源配置

- `bootstrap.yml`：Spring Cloud 启动配置，读取 Nacos 配置
- `logback-spring.xml`：日志配置
- `mapper/`：MyBatis XML 映射文件
- `db/migration/`：Flyway 数据库迁移脚本

### Nacos 配置文件

示例工程的主要配置通过 Nacos 配置中心管理。以下是 `mole-modules-example.yml`（Nacos 配置文件）的内容示例（已隐藏敏感信息）：

```yaml
server:
  port: 8080

security:
  oauth2:
    client:
      resourceId: ${spring.application.name}
    # 当业务服务与用户中心（mole-user）不在一个集群时，可以使用RemoteTokenService配置鉴权
    remote-token-check:
      clientId: XXXX
      clientSecret: XXXXXX
      checkTokenUrl: http://X.X.X.X:8600/oauth/check_token

spring:
  datasource:
    dynamic:
      primary: master
      strict: false
      datasource:
        master:
          username: ${DB_USERNAME:root}
          password: ${DB_PASSWORD:****}
          url: jdbc:mysql://${DB_HOST:X.X.X.X:3306}/${DB_NAME:test}?serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=utf-8&useSSL=false
          driver-class-name: com.mysql.cj.jdbc.Driver
  flyway:
    baseline-on-migrate: true
    baseline-version: 1.0.0

mybatis-plus:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

# 预制密钥（生产环境请使用环境变量配置）
secret:
  preSecretKey: ${PRE_SECRET_KEY:****}

ignore:
  urls:
    - /doc.html
    - /**/swagger-resources/**
    - /v2/api-docs
    - /webjars/**
```

### 配置说明

1. **OAuth2 配置**：
   - `security.oauth2.remote-token-check.clientId`：OAuth2 客户端ID
   - `security.oauth2.remote-token-check.clientSecret`：OAuth2 客户端密钥
   - `security.oauth2.remote-token-check.checkTokenUrl`：Token 验证地址

2. **数据库配置**：
   - `spring.datasource.dynamic.datasource.master`：主数据源配置
   - 支持通过环境变量配置：`DB_HOST`、`DB_NAME`、`DB_USERNAME`、`DB_PASSWORD`

3. **密钥配置**：
   - `secret.preSecretKey`：预制密钥（生产环境请使用环境变量 `PRE_SECRET_KEY` 配置）

4. **忽略 URL 配置**：
   - `ignore.urls`：Swagger API 文档相关的 URL，不需要 Token 验证

## 许可证

本项目使用 MIT 许可证 - 查看 LICENSE 文件了解详情