# eagle

**Repository Path**: sunjones/eagle

## Basic Information

- **Project Name**: eagle
- **Description**: eagle单体后端服务
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-17
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Eagle

基于 **Spring Boot 4.0** + **Java 25** 的企业级应用脚手架，采用领域驱动设计（DDD）+ Spring Modulith 模块化架构。

## 特性

- **DDD 分层架构** — 充血模型、聚合根、领域事件、六边形端口与适配器
- **Spring Modulith** — 编译期模块边界校验，天然为微服务拆分做准备
- **OAuth2 认证中心** — 基于 Spring Authorization Server，支持授权码（PKCE）、短信验证码、微信小程序/扫码登录
- **RBAC 权限控制** — 角色 + `@PreAuthorize` 细粒度接口鉴权
- **多级缓存** — Redis + Caffeine
- **审计日志** — 自动记录操作日志，支持定期清理
- **国际化** — 错误消息支持中/英文，`Accept-Language` 自动切换
- **GraalVM Native Image** — 支持编译为原生可执行文件

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | Spring Boot 4.0.3、Spring Security、OAuth2 Authorization Server |
| 语言 | Java 25（GraalVM Toolchain） |
| 构建 | Gradle 9.4.1 |
| 数据库 | MySQL（生产）/ H2（开发） |
| ORM | Spring Data JPA + Hibernate 7 |
| 缓存 | Redis + Caffeine |
| 模块治理 | Spring Modulith 2.0.5 |
| 对象映射 | MapStruct 1.6.3 |
| API 文档 | SpringDoc OpenAPI 3.0.2（Swagger UI） |
| 实时通信 | WebSocket（STOMP） |
| JSON | fastjson2 2.0.57 |
| 第三方 | 微信 SDK、阿里云 SMS |

## 模块结构

```
com.eagle
├── auth/       # 认证授权域 — 账号、OAuth2、微信/短信登录
├── system/     # 系统管理域 — 用户、角色、部门、岗位、字典、日志
├── config/     # 全局配置 — Security、Cache、Async、i18n
└── common/     # 共享内核 — 异常体系、错误码、基类、跨域事件
```

**模块依赖方向：**

```
auth  ──────────────────────────────────▶ common
system ──▶ auth::port（六边形端口）──▶ common
config ──▶ auth::security           ──▶ common
```

auth 对任何业务模块零依赖，system 通过实现 auth 的出站端口（Driven Port）提供授权信息。

## 快速开始

### 环境要求

- JDK 25+（推荐 GraalVM）
- MySQL 8.0+（或使用内置 H2）
- Redis（可选，用于缓存）

### 运行

```bash
# 克隆项目
git clone https://github.com/your-username/eagle.git
cd eagle

# 开发模式启动（H2 内存数据库）
./gradlew bootRun

# 访问
# Swagger UI: http://localhost/swagger-ui/index.html
# 登录页面:   http://localhost/login
# 默认管理员: admin / 123456
```

### 构建

```bash
./gradlew build                  # 编译 + 测试
./gradlew test                   # 运行测试
./gradlew nativeCompile          # GraalVM Native Image
```

## API 概览

| 模块 | 端点 | 说明 |
|------|------|------|
| 账号 | `/accounts` | 注册、密码管理、锁定/解锁 |
| 短信 | `/sms` | 验证码发送 |
| OAuth | `/oauth-clients` | OAuth2 客户端管理 |
| 微信 | `/login/wechat` | 微信扫码/H5 登录 |
| 用户 | `/users` | 用户档案、角色/部门/岗位分配 |
| 角色 | `/roles` | 角色管理 |
| 部门 | `/depts` | 部门树管理 |
| 岗位 | `/posts` | 岗位管理 |
| 字典 | `/dicts` | 数据字典管理 |
| 日志 | `/logs` | 审计日志查询 |

所有接口均通过 `@PreAuthorize` 控制权限，详见 Swagger UI 文档。

## 认证方式

| 方式 | 说明 |
|------|------|
| 用户名密码 | OAuth2 授权码 + PKCE |
| 短信验证码 | 自定义 grant_type: `sms_code` |
| 微信小程序 | 自定义 grant_type: `wechat_mini_program` |
| 微信扫码 | Web OAuth2 回调 → Session 认证 |

## 架构设计

### 六边形架构（Ports & Adapters）

```
                    ┌─────────────────────┐
                    │     auth 域          │
                    │                     │
  Controller ──▶    │  Application        │
                    │       ↓             │
                    │  Domain             │
                    │    ├── Model        │
                    │    ├── Repository   │
                    │    └── Port ◄───────┼──── system 域实现（Adapter）
                    │       ↓             │
                    │  Infrastructure     │
                    └─────────────────────┘
```

### 跨域协作

- **事件驱动**：auth 发布 `AccountRegisteredEvent` → system 异步创建 User
- **端口调用**：auth 定义 `AuthorizationPort` → system 提供 `AuthorizationAdapter` 实现

### 模块边界治理

```bash
# PR 前必须通过
./gradlew test --tests "*.ModulithArchitectureTest"
```

Spring Modulith 在测试阶段静态扫描，检测循环依赖和非法跨模块访问。

### JSON 序列化：fastjson2 而非 Jackson ObjectMapper

项目使用 **fastjson2** 静态 API（`JSON.toJSONString` / `JSON.parseObject`）处理以下三个组件的序列化需求：

| 组件 | 用途 |
|------|------|
| `LoginRateLimitFilter` | 将 429 错误响应写入 HTTP 输出流 |
| `TokenTrackingHandler` | 解析 JWT payload 中的 `jti`/`sub` claim |
| `OnlineUserAdapter` | 在线用户信息写入 / 读取 Redis |

**原因**：上述三个组件均标注 `@Component`，在 Spring Security filter chain 初始化阶段（容器启动早期）就会被实例化。而 Spring Boot 自动配置的 `ObjectMapper` Bean（`JacksonAutoConfiguration`）注册时机较晚，若通过构造器注入会产生 Bean 初始化顺序问题，导致启动失败。

fastjson2 的静态方法不依赖 Spring 容器，彻底规避了这条耦合链。项目其余场景（HTTP 消息转换、序列化配置等）仍由 Spring MVC 托管的 Jackson 负责，两者职责不重叠。

## 配置

关键配置项（`application.yml`）：

```yaml
eagle:
  admin:
    username: admin
    password: ${EAGLE_ADMIN_PASSWORD:123456}
  log:
    cleanup:
      enabled: true
      retention-days: 90        # 审计日志保留天数
      cron: "0 0 2 * * ?"      # 每天凌晨 2 点清理
  oauth:
    default-client:
      client-id: eagleWeb
      require-proof-key: true   # PKCE
  wechat:
    mini-program:
      app-id: ${WECHAT_MINI_APP_ID:}
      app-secret: ${WECHAT_MINI_APP_SECRET:}
  sms:
    aliyun:
      access-key-id: ${ALIYUN_SMS_ACCESS_KEY_ID:}
      sign-name: ${ALIYUN_SMS_SIGN_NAME:}
```

## License

[Apache License 2.0](LICENSE)