# smart-stage-archetype

**Repository Path**: yaozd/smart-stage-archetype

## Basic Information

- **Project Name**: smart-stage-archetype
- **Description**: 一个基于 Smart Stage 的 Maven Archetype 模板，用于快速构建标准化的Java基础应用项目
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-02-03
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Smart Stage Archetype

一个基于 [Smart Stage](https://github.com/a466350665/smart-stage) 的 Maven Archetype 模板，用于快速构建标准化的Java基础应用项目，核心特性包括：插件化架构与聚合部署支持。

## 功能概览

- 生成标准三模块工程：`-api`、`-service`、`-boot`
- 统一的父工程与模块依赖管理
- 预置 MyBatis-Plus 与 MySQL 依赖（service 模块）
- 预置 Spring Boot 可执行模块与 Dockerfile（boot 模块）
- 提供示例初始化脚本 `init.sql`

## 环境要求

- Maven 3.6+（建议）
- 生成工程建议使用 **JDK 17**（Smart-Stage 2.0.0 基于 Spring Boot 3.x）

## 项目结构

生成的项目包含以下三个模块：

```
${rootArtifactId}/
├── ${rootArtifactId}-api/        # API 层
│   └── src/main/java/
│       ├── api/                  # API 接口定义
│       │   ├── dto/              # 数据传输对象
│       │   └── *.java            # Feign 接口
│   
├── ${rootArtifactId}-service/     # 服务层
│   └── src/main/java/
│       ├── controller/          # 控制器
│       ├── service/             # 业务逻辑
│       ├── mapper/              # MyBatis Mapper
│       ├── entity/              # 实体类
│       └── enums/               # 枚举类
│   └── src/main/resources/
│       └── plugin/${symbol}/    # 插件配置
│   
└── ${rootArtifactId}-boot/       # 启动模块
    ├── src/main/java/
    │   └── BootApplication.java # 应用启动类
    ├── src/main/resources/
    │   ├── application.yaml      # 主配置文件
    │   └── messages_*.properties # 国际化配置
    └── Dockerfile               # Docker 镜像构建文件
```

## 快速开始

### 1. 安装 Archetype

将 archetype 安装到本地仓库：

```bash
mvn clean install
```

### 2. 使用 Archetype 生成项目

交互式创建项目：

```bash
mvn archetype:generate \
  -DarchetypeGroupId=io.github.openjoe \
  -DarchetypeArtifactId=smart-stage-archetype \
  -DarchetypeVersion=2.0.0
```

### 3. 配置参数

在交互过程中，你需要配置以下参数：

| 参数 | 说明           | 示例            |
|------|--------------|---------------|
| `groupId` | 项目组织 ID      | `com.smart` |
| `artifactId` | 项目标识 ID      | `smart-stage-sample1` |
| `version` | 项目版本         | `1.0.0-SNAPSHOT`       |
| `package` | Java 包名      | `com.smart.stage.sample1` |
| `symbol` | 插件标识（用于配置目录） | `sample1`        |

### 4. 完整示例

使用命令行参数直接创建项目：

```bash
mvn archetype:generate \
    -DarchetypeGroupId=io.github.openjoe \
    -DarchetypeArtifactId=smart-stage-archetype \
    -DarchetypeVersion=2.0.0 \
    -DgroupId=com.smart \
    -DartifactId=smart-stage-sample1 \
    -Dversion=1.0.0-SNAPSHOT \
    -Dpackage=com.smart.stage.sample1 \
    -Dsymbol=sample1 \
    -DinteractiveMode=false
```

### 5. 初始化数据库

执行项目根目录下的 `init.sql` 脚本：

```bash
mysql -u root -p your_database < init.sql
```

### 6. 配置数据库

修改 `${rootArtifactId}-boot/src/main/resources/application.yaml` 中的数据库配置：

```yaml
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/your_database
    username: root
    password: your_password
```

### 7. 运行项目

```bash
cd ${rootArtifactId}-boot
mvn spring-boot:run
```

或打包后运行：

```bash
mvn clean package
java -jar ${rootArtifactId}-boot/target/${rootArtifactId}.jar
```

## 模块结构
```
${rootArtifactId}                                应用名称
├── ${rootArtifactId}-api                        API 接口定义模块，提供Feign接口示例
├── ${rootArtifactId}-service                    业务逻辑实现模块，提供基础CRUD示例，Controller、Service、Mapper结构分层
└── ${rootArtifactId}-boot                       应用启动模块，提供应用入口
  ```

## 依赖说明

生成的项目依赖以下组件：

- **smart-stage-core**: 核心组件
- **smart-stage-starter-mybatisplus**: MyBatis-Plus 集成
- **spring-cloud-starter-openfeign**: OpenFeign（可选）

## 可选配置

### Nacos 服务发现

取消注释 `application.yaml` 中的 Nacos 配置：

```yaml
spring:
  cloud:
    nacos:
      discovery:
        enabled: true
        server-addr: 127.0.0.1:8848
```

### Actuator 监控

在 `${rootArtifactId}-boot/pom.xml` 中取消注释：

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
```

### Swagger/OpenAPI 文档

在 `${rootArtifactId}-boot/pom.xml` 中取消注释：

```xml
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>
```

访问地址：`http://localhost:8080/swagger-ui/index.html`

## 配置项示例

以下示例以生成后的工程为参考，适用于基于 Smart Stage 的常见项目。

### 基础应用配置（application.yaml）

```yaml
server:
  port: 8080

spring:
  application:
    name: ${rootArtifactId}

  datasource:
    url: jdbc:mysql://127.0.0.1:3306/your_database?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=GMT%2B8
    username: root
    password: your_password
```

### Nacos（可选）

```yaml
spring:
  cloud:
    nacos:
      discovery:
        enabled: true
        server-addr: 127.0.0.1:8848
```

### Smart Stage 配置（示意）

```yaml
smart:
  stage:
    i18n:
      enabled: true
    mybatis-plus:
      page-db-type: mysql
```

> `page-db-type` 通常无需配置，只有在需要指定数据库分页语法时使用（如 OceanBase MySQL/Oracle 模式）。

## 配置说明

- 应用基础配置：各 boot 模块 `application.yaml`。
- 国际化资源：各 boot 模块 `messages_zh_CN.properties` 与 `messages_en_US.properties`。
- 插件级配置：
    - [Smart Stage](https://github.com/a466350665/smart-stage) 会自动加载 `plugin/*` 下的配置与资源，适合“按模块/插件”组织业务配置。
    - 约定目录结构：
      ```
      plugin/
      └── ${symbol}/
          ├── application.yaml
          ├── application-dev.yaml
          ├── messages_zh_CN.properties
          └── messages_en_US.properties
      ```

    - 加载规则：
        - `plugin/*/application.yml|yaml|properties` 会被自动加载，支持 profile（如 `application-dev.yaml`）
        - `plugin/*/messages*.properties` 作为国际化资源加载

## 许可证

[Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0)

## 相关链接

- [Smart Stage](https://github.com/a466350665/smart-stage)
- [Maven Archetype](https://maven.apache.org/archetype/)