本地开发

IDEA 配置

首次打开项目后，需完成以下配置：

JDK 配置

1. 打开 File → Project Structure → SDKs，添加 JDK 25
2. 打开 File → Project Structure → Project，设置 Project SDK 为 JDK 25

Gradle 配置

1. 打开 File → Settings → Build → Build Tools → Gradle
2. 设置 Gradle JVM 为 JDK 25
3. 勾选 Use Gradle from: 'gradle-wrapper.properties' file

注解处理器

1. 打开 File → Settings → Build → Annotation Processors
2. 勾选 Enable annotation processing

开发环境配置

Profile 机制

项目通过 Spring Boot Profile 区分环境：

Profile	说明	配置文件
dev	开发环境（默认）	application-dev.yml
uat	预发布环境	application-uat.yml
prod	生产环境	application-prod.yml

Nacos 配置中心

远程配置通过 Nacos 管理，application.yml 中通过 spring.config.import 导入：

spring:
  config:
    import:
      - optional:nacos:common.yml?group=guava&refreshEnabled=true
      - optional:nacos:admin.yml?group=guava&refreshEnabled=true

各环境的 Nacos namespace / group 不同：

环境	namespace	group
dev	foton-ses-dev	guava
uat / prod	jdk25	jdk25

启动项目

启动入口

各微服务启动类与端口：

服务	启动类	端口
网关	BootGatewayApplication	7001
认证	BootLoginApplication	7002
后台管理	BootAdminApplication	7003
文件存储	BootFileStoreApplication	7004
Redis 缓存	BootRedisApplication	7005
MQ 生产者	BootMqProviderApplication	7006
MQ 消费者	BootMqConsumerApplication	7007

启动方式

1. 在 IDEA 中打开项目根目录，等待 Gradle 同步完成
2. 找到启动类 BootAdminApplication（路径：src/main/java/com/guava/admin/BootAdminApplication.java）
3. 点击类名左侧的绿色箭头 ▶，或右键 → Run 'BootAdminApplication'

TIP

项目已通过 build.gradle.kts 自动注入 JVM 参数，无需手动配置：

--enable-native-access=ALL-UNNAMED
--sun-misc-unsafe-memory-access=allow

启动成功后访问：

http://localhost:7003/

切换环境

默认使用 dev profile。如需切换环境：

1. 点击 IDEA 工具栏的运行配置下拉框 → Edit Configurations...
2. 找到 BootAdminApplication 配置
3. 在 Active profiles 中输入：dev / uat / prod

Gradle 命令行启动（备选）

# 默认 dev profile
./gradlew :guava-admin-starter:bootRun

# 指定环境
./gradlew :guava-admin-starter:bootRun --args='--spring.profiles.active=uat'

API 文档

项目使用 Knife4j + Springdoc OpenAPI 生成 API 文档。

启动服务后访问：

http://localhost:7003/doc.html

注解使用

@Tag(name = "用户管理")
@RestController
@RequestMapping("/sysuser")
public class SysUserController {

    @Operation(summary = "查询用户列表")
    @GetMapping("/list")
    public IPage<Map<String, Object>> findUsers() { }
}

常见问题（开发阶段）

现象	处理
启动报错 IllegalAccessError / InaccessibleObjectException	JDK 25 默认限制原生 API 访问，确认 JVM 参数已添加
Nacos 配置未生效	确认 spring.config.import 格式正确，namespace / group 与 Nacos 控制台一致
MyBatis Mapper 找不到	确认启动类有 @MapperScan("com.guava.admin.repository")
Lombok 方法（getter/setter）报找不到	确认已安装 Lombok 插件 + 启用 Annotation Processing
端口被占用	杀掉占用进程或修改 server.port

更多问题见 FAQ - 后端。

下一步

开发完成后，参见 生产构建 打包可执行 JAR。