101 lines
6.8 KiB
Markdown
101 lines
6.8 KiB
Markdown
# abacus.base.demo
|
||
|
||
是前后端分离的基于 Spring Boot 的基础项目，作为使用 agent 应用开发前后端项目的**基础模板**。本项目自身不包含业务 Java 代码，业务能力由 abacus 框架（`abacus.config`、`abacus.commons`、`abacus.fundation`、`abacus.business.service` 等）提供，开发者/agent 在本模板上添加业务模块即可。
|
||
|
||
|
||
|
||
## 技术栈
|
||
|
||
| 项 | 说明 |
|
||
| --- | --- |
|
||
| 构建 | Maven，父工程 `abacus.framework:abacus.springcloud.pom:1.5.0` |
|
||
| 框架 | Spring Boot + abacus 系列框架（配置、通用、基础、业务服务） |
|
||
| 注册/配置中心 | Nacos（见 `bootstrap.yml`） |
|
||
| 数据库 | MySQL / SQL Server / Oracle / 达梦，Druid 连接池 + JPA |
|
||
| 定时任务 | XXL-JOB（`application-xxljob.yml`） |
|
||
| 消息队列 | Kafka |
|
||
| 接口文档 | springdoc（OpenAPI） |
|
||
| 监控 | Spring Actuator + Prometheus |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
abacus.base.demo/
|
||
├── pom.xml # Maven 构建配置：依赖、多环境 profile(dev/test/prod)、打包插件
|
||
├── assembly.xml # Maven 发布包(zip)打包规则：jar + doc + sql + html
|
||
├── .project / .classpath # Eclipse IDE 工程配置（Java + Maven 项目）
|
||
├── .settings/ # Eclipse 偏好配置（编码、JDK、m2e）
|
||
├── src/
|
||
│ └── main/
|
||
│ ├── java/ # 【业务代码目录】Java 源码（当前为空，新增业务代码放这里）
|
||
│ ├── resources/
|
||
│ │ ├── config/
|
||
│ │ │ ├── dev/ # dev 环境配置（Maven profile 默认激活）
|
||
│ │ │ │ ├── application.yml # 主配置：端口、数据源、JPA、Druid、Kafka、springdoc、abacus 扫描路径等
|
||
│ │ │ │ ├── bootstrap.yml # 启动引导配置：应用名、Nacos 注册中心/配置中心
|
||
│ │ │ │ ├── application-xxljob.yml # XXL-JOB 调度中心与执行器配置
|
||
│ │ │ │ ├── logback-spring.xml # 应用日志配置
|
||
│ │ │ │ └── logback-access.xml # 访问日志配置
|
||
│ │ │ ├── test/ # test 环境配置（与 dev 文件同名同结构）
|
||
│ │ │ └── prod/ # prod 环境配置（与 dev 文件同名同结构）
|
||
│ │ ├── doc/
|
||
│ │ │ └── 升级日志.md # 版本升级日志，按版本记录更新说明
|
||
│ │ ├── sql/
|
||
│ │ │ ├── table/
|
||
│ │ │ │ ├── mysql.sql # MySQL 建表 DDL（示例表 example_category）
|
||
│ │ │ │ └── sqlserver.sql # SQL Server 建表 DDL（与 mysql.sql 对应）
|
||
│ │ │ ├── data/
|
||
│ │ │ │ └── sqlserver.sql # 初始化数据（acas 子系统/菜单/模块注册）
|
||
│ │ │ └── upgrade.xml # 数据库版本升级 SQL 配置（按版本号执行，支持多库语法翻译）
|
||
│ │ ├── vue/ # 【Vue 项目源码目录】存放 vue 项目，映射过来的，前后端分离（当前为空）
|
||
│ │ └── html/ # 【前端构建产物目录】存放 vue 项目编译后的 html 等静态资源（当前为空，由 assembly.xml 打入发布包）
|
||
│ └── (META-INF) # 若存在，会按 pom.xml 配置打入发布包
|
||
└── target/ # Maven 构建输出目录（编译产物、打包 zip，可忽略/删除）
|
||
```
|
||
|
||
## 关键配置说明（agent 开发时必须了解）
|
||
|
||
### 1. pom.xml
|
||
- 多环境 profile：`dev`（默认）/ `test` / `prod`，通过 `-P` 指定，决定加载 `src/main/resources/config/<env>/` 下的配置。
|
||
- 打包资源：仅打包 `META-INF`、当前环境 config 目录、`sql/**` 到 jar 内；`doc`、`sql`、`html` 通过 `assembly.xml` 额外打入 zip 发布包。
|
||
- 发布包：`mvn package` 生成 `${artifactId}-${version}-bin.zip`（含 jar + doc + sql + html）。
|
||
|
||
### 2. application.yml（以 dev 为例，三个环境结构一致）
|
||
- `server.port`：服务端口（示例 9003）。
|
||
- `spring.datasource`：Druid 数据源；`enableMultiSource` 可开启多数据源（`multidb0~multidb9` 预设 10 个），含 `defaultDB` 默认库、`readDB` 读库、`dynamicRelation` 业务路由配置。
|
||
- `spring.jpa`：JPA/Hibernate 配置，命名策略使用框架的 `LowercaseNamingStrategyStandardImpl`。
|
||
- `spring.kafka`：Kafka 生产/消费配置。
|
||
- `springdoc.packages-to-scan`：在线接口文档扫描的包路径。
|
||
- `abacus.controllerPackages` / `abacus.entitypackages`：**框架扫描 Controller 与实体的包路径，新增业务代码必须将包名加入此配置**（示例包前缀 `abacus.springboot.example`）。
|
||
- `abacus.responseExcludePath`：不被统一响应体包装器拦截的 URI。
|
||
- `management.endpoints.web.base-path`：Actuator 端点基础路径（`/services/actuator`）。
|
||
|
||
### 3. bootstrap.yml
|
||
- `spring.application.name`：应用名（示例 `example`），Nacos 中需唯一。
|
||
- `spring.cloud.nacos`：Nacos 服务地址、账号、命名空间；通过 `extension-configs` 引入公共配置（`abacus-discovery.yml`、`abacus-acas.yml`、`abacus-redis.yml` 等）。
|
||
|
||
### 4. sql/ 目录
|
||
- `table/`：建表 DDL，按数据库分文件（mysql.sql / sqlserver.sql），新建业务表需同步维护两个文件。
|
||
- `data/`：初始化数据（子系统、菜单、模块注册，依赖 acas 框架）。
|
||
- `upgrade.xml`：版本化升级 SQL，`<upgrade version="yyyy-MM-dd[.count]">` 按版本升序执行；`translator="true"` 时以 SQL Server 语法编写，由框架翻译到各数据库。
|
||
|
||
## 给 agent 的开发约定
|
||
|
||
1. **新增 Java 代码**：放入 `src/main/java`，包名建议以 `abacus.springboot.应用名.*` 为前缀（保持框架扫描配置一致，或同步修改 `application.yml` 中 `abacus.controllerPackages` / `springdoc.packages-to-scan` / `abacus.entitypackages`）。
|
||
2. **新增前端 Vue 项目**：Vue 源码放在 `src/main/resources/vue/`，构建（编译）产物输出到 `src/main/resources/html/`，由 `assembly.xml` 自动打入发布包。
|
||
3. **新增配置项**：优先写入 `src/main/resources/config/<env>/application.yml` 对应环境，环境间保持字段一致。
|
||
4. **数据库变更**：建表写 `sql/table/`，历史变更写 `sql/upgrade.xml`，初始化数据写 `sql/data/`。
|
||
5. **文档与日志**：功能更新记录到 `src/main/resources/doc/升级日志.md`。
|
||
6. **打包产物**：`target/` 目录为构建输出，无需维护；发布包为 `target/*-bin.zip`。
|
||
7. **多环境配置**：修改配置时需同步 `dev` / `test` / `prod` 三个目录（或按需仅改某环境）。
|
||
8. **pom.xml**：`<artifactId></artifactId>`建议以`abacus.springboot.应用名`设置
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|