# lemon-admin-server

**Repository Path**: aiy/lemon-admin-server

## Basic Information

- **Project Name**: lemon-admin-server
- **Description**: 基于 JDK 17 + Spring Boot 4 + Spring Security 构建的前后端分离权限管理系统。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lemon Admin Server

基于 Java 17、Spring Boot 4、Spring Security、MyBatis-Plus 的后台服务端模板项目。

这个仓库的目标不是只做一个固定业务后台，而是沉淀一套可复用的服务端基础能力：认证授权、系统管理、通用 CRUD、代码生成、接口文档、文件存储、短信/邮件/微信小程序集成等。后续开发新项目时，可以以此为基础快速裁剪和扩展。

## 技术栈

- Java 17
- Spring Boot 4
- Spring Security
- MyBatis-Plus
- MySQL
- Redis
- MapStruct
- NextDoc4j / OpenAPI
- Fastexcel
- MinIO / Aliyun OSS

## 目录结构

```text
src/main/java/com/lemon/boot
├── auth        # 登录认证相关接口和服务
├── common      # 通用注解、基础类、枚举、统一响应、工具类
├── framework   # 基础设施：安全、Web、MyBatis、OpenAPI、缓存、第三方集成
├── module      # 可选业务模块：文件、代码生成、演示模块等
└── system      # 后台基础系统：用户、角色、菜单、部门、字典、配置、通知等
```

## 环境要求

- JDK 17+
- Maven 3.9+
- MySQL 8.x，或兼容版本
- Redis 6+

## 快速启动

1. 初始化数据库

   执行 `sql/` 目录下的数据库脚本，创建基础表和初始化数据。

2. 准备环境变量

   可参考 [.env.example](.env.example) 配置数据库、Redis、JWT、OSS、短信等变量。

   常用变量：

   ```text
   MYSQL_HOST=localhost
   MYSQL_PORT=3306
   MYSQL_DATABASE=lemon_admin
   MYSQL_USERNAME=root
   MYSQL_PASSWORD=123456

   REDIS_HOST=localhost
   REDIS_PORT=6379
   REDIS_PASSWORD=
   ```

3. 启动项目

   ```bash
   mvn spring-boot:run
   ```

4. 访问接口文档

   ```text
   http://localhost:8080/doc.html
   ```

## 编译和测试

```bash
mvn -q -DskipTests compile
mvn -q test
```

不要并行执行多个 Maven 编译/测试命令。MapStruct 会写入 `target/generated-sources/annotations`，并行执行可能导致生成文件互相覆盖。

## 通用 CRUD 约定

项目内置了一套基础 CRUD 封装：

```text
AbstractCrudController
BaseService
BaseServiceImpl
BaseMapperX
BaseConverter
BaseQuery
BaseReq
BaseResp
```

自动 CRUD 接口风格：

```text
GET  /api/v1/{module}/page
GET  /api/v1/{module}/list
GET  /api/v1/{module}/get/{id}

POST /api/v1/{module}/create
POST /api/v1/{module}/update/{id}
POST /api/v1/{module}/delete/{id}
POST /api/v1/{module}/delete/batch
```

简单模块优先使用基础 CRUD 封装，复杂业务可以覆盖 Controller 或 Service 中的具体方法。

## 代码生成

代码生成模板位于：

```text
src/main/resources/templates/codegen
```

后端模板已经对齐当前基础 CRUD 体系，生成代码会优先使用 `AbstractCrudController`、`BaseServiceImpl`、`BaseMapperX` 和 `BaseConverter`。

如果调整基础 CRUD 接口风格，需要同步更新：

```text
templates/codegen/backend
templates/codegen/frontend
```

## 接口文档

项目使用 NextDoc4j，入口：

```text
/doc.html
```

如果新增 Controller 后文档中没有显示，优先检查：

```text
springdoc.group-configs[*].packages-to-scan
```

配置文件：

```text
src/main/resources/application-dev.yml
src/main/resources/application-prod.yml
```

## 模板项目建议

新项目基于本仓库开发时，建议先做这些裁剪：

- 修改 `spring.application.name`、`groupId`、`artifactId`
- 替换数据库名和初始化 SQL
- 删除不需要的第三方集成，例如短信、微信小程序、OSS
- 保留 `system` 基础后台能力，按需裁剪菜单和权限
- 保留 `common`、`framework`、`module/codegen`
- 根据业务模块更新 `springdoc.group-configs.packages-to-scan`

## 注意事项

- 不要重新引入 Knife4j，本项目已切换到 NextDoc4j。
- 文档和静态资源请求已在 `RequestLogFilter` 中排除，避免污染业务请求日志。
- 安全白名单请通过 `security.ignore-urls` 和 `security.unsecured-urls` 配置，不要直接放宽全局安全过滤器。
- 模板项目中不要提交本地生成文件、IDE 缓存、私有密钥或真实第三方凭据。