# account-java

**Repository Path**: grow-project/account-java

## Basic Information

- **Project Name**: account-java
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-02
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# account-java

企业级后台管理系统后端，基于 **JDK 21 + Spring Boot 3.5.7 + Maven 多模块**，采用「单体应用 + 模块化」架构。

> 多模块 ≠ 微服务。所有业务模块最终由 `admin-boot` 统一启动，后续可按模块平滑拆分。

- 版本：`1.0.0-SNAPSHOT`
- 端口：`8081`
- 分支：`main`
- 仓库：`git@gitee.com:grow-project/account-java.git`

## 目录

- [技术栈](#技术栈)
- [模块结构](#模块结构)
- [模块依赖关系](#模块依赖关系)
- [包结构说明](#包结构说明)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [接口验证](#接口验证)
- [配置说明](#配置说明)
- [Make 快捷命令](#make-快捷命令)
- [常见问题](#常见问题)
- [已完成](#已完成)
- [后续规划](#后续规划)
- [开发约定](#开发约定)

## 技术栈

| 技术 | 版本 | 状态 | 说明 |
| --- | --- | --- | --- |
| Java | 21 (LTS) | 已使用 | 开发语言 |
| Spring Boot | 3.5.7 | 已使用 | 后端框架 |
| Maven | 3.9+ | 已使用 | 项目构建 |
| Spring Web | 随 Spring Boot | 已使用 | MVC / REST |
| Spring Validation | 随 Spring Boot | 已引入 | 参数校验 |
| Lombok | 由 Spring Boot BOM 管理 | 已使用 | 简化实体类 |
| MySQL | 8.0+ | 待集成 | 关系型数据库 |
| MyBatis-Plus | 3.5.x | 待集成 | ORM 框架 |
| Redis | 7.x | 待集成 | 缓存 / 登录状态 |
| Spring Security + JWT | 随 Spring Boot | 待集成 | 认证授权 |
| Knife4j | 4.x | 待集成 | API 文档 |

## 模块结构

```
account-java
├── pom.xml                 # 父工程：统一版本、子模块、插件
├── Makefile                # 构建 / 启动 / 日志快捷命令
├── README.md
├── AGENTS.md               # 开发约定与 Commit 规范
├── admin-common            # 公共基础：常量、枚举、异常、统一响应、工具类
├── admin-framework         # 框架能力：config、security、redis、mybatis、web
├── admin-system            # 系统管理：用户、角色、菜单、部门
├── admin-generator         # 代码生成（待实现）
├── admin-job               # 定时任务（待实现）
└── admin-boot              # 启动模块：AdminApplication + 配置 + 打包插件
```

各模块职责：

| 模块 | 职责 | 可独立启动 | 打包方式 |
| --- | --- | --- | --- |
| admin-boot | 应用启动、整合各模块 | 是 | 可执行 JAR |
| admin-common | 公共工具、异常、统一响应 | 否 | 普通 JAR |
| admin-framework | 框架配置、安全认证 | 否 | 普通 JAR |
| admin-system | 用户、角色、菜单、部门 | 否 | 普通 JAR |
| admin-generator | 代码生成 | 否 | 普通 JAR |
| admin-job | 定时任务 | 否 | 普通 JAR |

`admin-system` 内部按分层组织：`controller`、`service`（含 `impl`）、`mapper`、`entity`、`dto`、`vo`。

## 模块依赖关系

```
                  admin-boot
                      │
          ┌───────────┼──────────────┐
          ▼           ▼              ▼
     admin-system  admin-job   admin-generator
          │           │              │
          ▼           │              │
    admin-framework   │              │
          │           │              │
          └───────────┼──────────────┘
                      ▼
                 admin-common
```

- `admin-common` 为最底层模块，**不允许反向依赖**其他业务模块，否则会产生循环依赖（Maven 不允许模块间循环依赖）。
- 依赖版本统一在父工程 `dependencyManagement` 中声明，子模块引入时无需写版本号。
- 只有 `admin-boot` 配置 `spring-boot-maven-plugin` 生成可执行 JAR，其余模块为普通 JAR。
- Maven 会依据模块依赖自动决定构建顺序，无需手工排序。

## 包结构说明

所有模块的 Java 包均位于 `com.example.admin` 之下：

```
com.example.admin
├── AdminApplication          # 启动类（admin-boot）
├── common                    # admin-common
├── framework                 # admin-framework
├── system                    # admin-system
├── generator                 # admin-generator
└── job                       # admin-job
```

Spring 的组件扫描依据 **Java 包路径** 而非 Maven 模块名，启动类放在 `com.example.admin` 即可扫描所有模块中的 Bean，无需额外配置 `scanBasePackages`。

## 环境要求

- JDK 21
- Maven 3.9+
- make（可选，用于快捷命令）

本机开发环境安装在用户目录，已写入 `~/.zshrc`：

```bash
# Java 21 + Maven
export JAVA_HOME="$HOME/opt/jdk-21.0.13+9"
export MAVEN_HOME="$HOME/opt/apache-maven-3.9.9"
export PATH="$JAVA_HOME/bin:$MAVEN_HOME/bin:$PATH"
```

验证：

```bash
java -version    # openjdk version "21.0.13"
mvn -version     # Apache Maven 3.9.9
```

## 快速开始

### 方式一：Make（推荐）

```bash
make build            # mvn clean install
make start            # 后台启动
make verify           # 验证接口
make logs             # 查看日志
make stop             # 停止服务
```

### 方式二：Maven

构建全部模块：

```bash
mvn clean install
```

仅构建启动模块及其依赖：

```bash
mvn clean package -pl admin-boot -am
```

启动：

```bash
java -jar admin-boot/target/admin-boot-1.0.0-SNAPSHOT.jar
```

也可在 IDEA 中直接运行 `com.example.admin.AdminApplication`。

启动成功日志：

```
Tomcat started on port 8081 (http) with context path '/'
Started AdminApplication in 2.159 seconds
```

## 接口验证

```bash
curl http://localhost:8081/system/user/info
```

响应：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "admin",
    "nickname": "管理员"
  }
}
```

该接口用于验证：子模块引用、跨模块 Controller 扫描、统一响应结构、HTTP 服务可用性。

| 接口 | 方法 | 说明 |
| --- | --- | --- |
| `/system/user/info` | GET | 返回示例用户信息（演示接口） |

> `code` 为业务响应码，与 HTTP 状态码不是同一概念，后续将通过全局异常处理统一映射。

## 配置说明

| 文件 | 作用 |
| --- | --- |
| `admin-boot/src/main/resources/application.yml` | 主配置：端口、应用名、激活 profile、日志级别 |
| `admin-boot/src/main/resources/application-dev.yml` | dev 环境配置：端口 |

当前未接入 MySQL、Redis 等中间件，先保证项目骨架稳定启动，再逐个集成便于定位问题。

服务端口为 **8081**（本机 8080 已被其他进程占用），可在 `application.yml` 中修改。

## Make 快捷命令

项目根目录提供 `Makefile`，执行 `make help` 查看：

| 命令 | 说明 |
| --- | --- |
| `make help` | 显示所有可用命令 |
| `make build` | 构建全部模块（`mvn clean install`） |
| `make package` | 仅打包启动模块及其依赖 |
| `make clean` | 清理构建产物 |
| `make run` | 前台启动（Ctrl+C 停止，jar 不存在时自动构建） |
| `make start` | 后台启动，日志输出到 `logs/admin-boot.log` |
| `make stop` | 停止后台服务 |
| `make restart` | 重启服务 |
| `make status` | 查看进程状态与接口 HTTP 状态 |
| `make logs` | 实时查看日志 |
| `make verify` | 调用 `/system/user/info` 验证接口 |

常用组合：

```bash
make package && make start && make verify
```

说明：

- 后台 PID 记录在 `.run/admin-boot.pid`，日志在 `logs/`，均已被 `.gitignore` 忽略。
- 端口可覆盖：`make start PORT=9090`（需与 `application.yml` 保持一致）。
- `make stop` 优先按 PID 文件停止，找不到时按进程命令行匹配兜底。
- 后台启动后会轮询健康接口，最多等待 30 秒；失败时自动输出日志尾部。

## 常见问题

**1. `zsh: command not found: mvn`**

环境变量未生效，执行 `source ~/.zshrc` 或新开终端。若仍未生效，检查 `~/.zshrc` 中是否包含上文的环境变量配置。

**2. 启动报 `BindException: 地址已在使用`**

端口被占用，可用 `lsof -i:8081` 或 `ss -tlnp | grep 8081` 定位，然后修改端口或停止占用进程。注意 `make restart` 会先释放端口再启动。

**3. `make stop` 后进程仍在**

执行 `make status` 确认状态；必要时手动执行 `pkill -f "java -jar admin-boot/target/admin-boot-*.jar"`。

**4. 打包后修改配置不生效**

配置文件被打进 JAR，修改 `src/main/resources` 下的配置后需重新打包（`make package`）。临时覆盖可用：

```bash
java -jar admin-boot/target/admin-boot-1.0.0-SNAPSHOT.jar --server.port=9090
```

## 已完成

- Maven 父工程与 6 个子模块初始化
- 模块依赖管理与版本统一
- 统一响应对象 `Result<T>`
- 跨模块 Controller 扫描验证
- `mvn clean install` 全模块构建通过
- 启动与接口联调验证通过
- Makefile 构建 / 启动 / 日志快捷命令

## 后续规划

| 阶段 | 任务 |
| --- | --- |
| 2 | MySQL 集成、数据源配置 |
| 3 | MyBatis-Plus 集成、CRUD |
| 4 | 统一响应结构完善 |
| 5 | 全局异常处理 |
| 6 | 参数校验（Jakarta Validation） |
| 7-8 | 用户管理与分页查询 |
| 9-10 | Spring Security + JWT 登录 |
| 11 | Redis 缓存与登录状态 |
| 12-14 | RBAC 权限、菜单管理、部门管理 |
| 15-16 | 操作日志、登录日志（AOP） |
| 17-18 | 文件上传、Excel 导入导出 |
| 19 | 定时任务（Spring Scheduling） |
| 20 | 代码生成器 |
| 21-22 | 单元测试、接口测试 |
| 23-24 | Docker 部署、CI/CD |

## 开发约定

- 统一使用 `Result<T>` 作为接口返回结构。
- 模块间依赖保持单向：`admin-common` ← `admin-framework` ← `admin-system` ← `admin-boot`。
- 通用能力（安全、缓存、ORM、Web）放在 `admin-framework`，业务代码放在 `admin-system` 等业务模块。
- 新增第三方依赖先在父工程 `dependencyManagement` 统一版本，再在子模块引入。
- 提交前执行 `make build`，保证全模块构建通过。