# Easy-Starter

**Repository Path**: Gem0921/Easy-Starter

## Basic Information

- **Project Name**: Easy-Starter
- **Description**: 好用的springboot-stater
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-19
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# Easy Starter

**一组开箱即用的 Spring Boot Starter 集合**

统一响应包装 · 自动分页 · 方法耗时统计 · JWT Token 验证 · XXL-JOB 集成 · Feign 响应解码

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.3.12-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-Hoxton.SR12-brightgreen.svg)](https://spring.io/projects/spring-cloud)
[![JDK](https://img.shields.io/badge/JDK-8%2B-orange.svg)](https://www.oracle.com/java/)

</div>

---

## 简介

Easy Starter 是一组轻量级、低侵入的 Spring Boot Starter 组件集合，把日常开发中重复的样板能力（响应包装、分页、Token 校验、链路耗时、任务调度、Feign 解码）抽象成开箱即用的模块。每个 Starter 都遵循「按需引入、配置开关、约定优于配置」的原则，引入依赖、打开开关即可使用，对业务代码几乎零侵入。

基于 Spring Boot 2.3.12 / Spring Cloud Hoxton.SR12 / Spring Cloud Alibaba 2.2.10-RC1 构建。

## 特性

- **按需引入** —— 每个能力独立成 Starter，用什么引什么，互不依赖。
- **配置即开关** —— 统一 `cn.smart.*` 配置前缀，一个 `enable` 属性控制启停。
- **低侵入** —— 基于 AOP、拦截器、`ResponseBodyAdvice` 等标准扩展点实现，不绑架业务代码。
- **统一约定** —— 共享 `smart-core` 中的响应体、异常、用户会话模型，多模块协同一致。
- **自动装配** —— 遵循 Spring Boot 自动配置规范，零 XML 配置。

## 模块一览

| 模块 | 能力 | 配置前缀 | 默认状态 |
|---|---|---|---|
| `smart-core` | 核心基础库（注解 / DTO / 异常 / 工具类） | - | - |
| `pagex-spring-boot-starter` | 自动分页 | `cn.smart.pagex` | 关闭 |
| `wapperx-spring-boot-starter` | 统一响应包装 | `cn.smart.wapperx` | 关闭 |
| `logtimex-spring-boot-starter` | 方法耗时统计 | `cn.smart.logtimex` | 关闭 |
| `tokenx-spring-boot-starter` | JWT Token 验证 | `cn.smart.tokenx` | 关闭 |
| `xxl-jobx-spring-boot-starter` | XXL-JOB 集成 | `cn.smart.xxljobx` | 关闭 |
| `common-feign-spring-boot-starter` | Feign 响应解码 | `cn.smart.decoderx` | **开启** |

## 环境要求

| 依赖 | 版本 |
|---|---|
| JDK | 8 及以上 |
| Maven | 3.6+ |
| Spring Boot | 2.3.12.RELEASE |
| Spring Cloud | Hoxton.SR12 |
| Spring Cloud Alibaba | 2.2.10-RC1 |

## 项目结构

```
easy-starter
├── smart-core                          # 核心基础库（注解、DTO、异常、工具类）
├── pagex-spring-boot-starter           # 自动分页 Starter
├── wapperx-spring-boot-starter         # 统一响应包装 Starter
├── logtimex-spring-boot-starter        # 方法耗时统计 Starter
├── tokenx-spring-boot-starter          # JWT Token 验证 Starter
├── xxl-jobx-spring-boot-starter        # XXL-JOB 集成 Starter
└── common-feign-spring-boot-starter    # Feign 响应解码 Starter
```

---

## smart-core - 核心基础库

所有 Starter 的公共依赖，提供注解定义、统一响应体、业务异常、用户会话等基础能力。

### BizException - 业务异常

- **位置**: `cn.smart.core.exception.BizException`
- **功能**: 自定义业务异常，携带错误码 `code` 和错误信息 `message`

```java
// 直接抛出
throw new BizException(400, "参数错误");

// 使用静态方法
BizException.throwBizException(400, "参数错误");
```

### ApiResponse - 统一响应体

- **位置**: `cn.smart.core.dto.ApiResponse<T>`
- **功能**: 统一 API 响应格式，包含 `code`、`message`、`data` 三个字段

```java
// 成功响应 -> {"code":0, "message":"成功", "data": ...}
ApiResponse.success(data);

// 错误响应 -> {"code":500, "message":"系统异常", "data": null}
ApiResponse.error(500, "系统异常");
```

### UserSession & UserContext - 用户会话

- **UserSession** (`cn.smart.core.model.UserSession`): 用户会话模型，包含 `id`、`tel`、`nickName`、`roles`、`permissions`
- **UserContext** (`cn.smart.core.util.UserContext`): 基于 ThreadLocal 的用户会话持有器

```java
// 获取当前登录用户
UserSession user = UserContext.get();
String tel = user.getTel();
List<String> roles = user.getRoles();
```

### 注解定义

| 注解 | 位置 | 作用域 | 说明 |
|---|---|---|---|
| `@PageX` | `cn.smart.core.annotation.PageX` | 方法 | 标记需要自动分页的方法 |
| `@LogTimeX` | `cn.smart.core.annotation.LogTimeX` | 方法 | 标记需要统计执行耗时的方法，支持 `value` 属性自定义描述 |
| `@NoWapperX` | `cn.smart.core.annotation.NoWapperX` | 类/方法 | 标记不需要统一响应包装的类或方法 |

---

## pagex-spring-boot-starter - 自动分页

基于 AOP + PageHelper 实现的自动分页 Starter。在方法上添加 `@PageX` 注解，即可自动拦截并注入分页参数。

### 引入依赖

```xml
<dependency>
    <groupId>cn.bs</groupId>
    <artifactId>pagex-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>
```

### 配置

```yaml
cn:
  smart:
    pagex:
      enable: true    # 启用自动分页（默认关闭）
```

### 使用方式

**方式一：通过 HTTP 请求参数传递分页参数**

请求时携带 `pageNum` 和 `pageSize` 查询参数：

```
GET /users?pageNum=1&pageSize=10
```

```java
@PageX
public List<User> listUsers() {
    return userMapper.selectAll();  // 自动分页
}
```

**方式二：通过方法参数传递分页参数**

让请求 DTO 实现 `PageParam` 接口：

```java
import cn.smart.pagex.api.PageParam;

public class UserQuery implements PageParam {
    private Integer pageNum;
    private Integer pageSize;
    // ... 其他查询条件

    @Override
    public Integer getPageNum() { return pageNum; }

    @Override
    public Integer getPageSize() { return pageSize; }
}
```

```java
@PageX
public List<User> listUsers(UserQuery query) {
    return userMapper.selectByCondition(query);  // 自动分页
}
```

> 优先级：方法参数中的 `PageParam` 优先于 HTTP 请求参数。

---

## wapperx-spring-boot-starter - 统一响应包装

基于 `ResponseBodyAdvice` 实现的统一响应包装 Starter。自动将 Controller 返回值包装为 `ApiResponse` 格式，并提供全局异常处理。

### 引入依赖

```xml
<dependency>
    <groupId>cn.bs</groupId>
    <artifactId>wapperx-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>
```

### 配置

```yaml
cn:
  smart:
    wapperx:
      enable: true    # 启用统一响应包装（默认关闭）
```

### 使用方式

**自动包装所有 Controller 返回值：**

```java
@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.getById(id);
    }
    // 响应: {"code":0, "message":"成功", "data":{"id":1, "name":"张三"}}
}
```

**排除特定方法或类的包装：**

```java
// 方法级别排除
@NoWapperX
@GetMapping("/health")
public String health() {
    return "ok";  // 直接返回 "ok"，不包装
}

// 类级别排除
@NoWapperX
@RestController
public class RawController {
    // 该类所有方法都不会被包装
}
```

**全局异常处理：**

- `BizException` -> `{"code": 异常码, "message": "异常信息", "data": null}`
- 其他异常 -> `{"code": 999, "message": "异常信息", "data": null}`

**PageHelper 分页结果自动处理：**

当返回值为 PageHelper 的 `Page` 对象时，自动提取为包含 `total` 和 `items` 的结构：

```json
{"code":0, "message":"成功", "data":{"total":100, "items":[...]}}
```

---

## logtimex-spring-boot-starter - 方法耗时统计

基于 AOP 实现的方法执行耗时统计 Starter。在方法上添加 `@LogTimeX` 注解，自动记录方法执行时间。

### 引入依赖

```xml
<dependency>
    <groupId>cn.bs</groupId>
    <artifactId>logtimex-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>
```

### 配置

```yaml
cn:
  smart:
    logtimex:
      enable: true    # 启用方法耗时统计（默认关闭）
```

### 使用方式

```java
@LogTimeX
public void processData() {
    // ... 耗时操作
}
// 日志输出: [com.example.MyService.processData] 执行耗时: 342 ms

@LogTimeX("导入用户数据")
public void importUsers() {
    // ... 耗时操作
}
// 日志输出: [导入用户数据] 执行耗时: 1024 ms
```

---

## tokenx-spring-boot-starter - JWT Token 验证

基于 Spring MVC 拦截器 + Hutool JWT 实现的 Token 验证 Starter。自动验证请求头中的 JWT Token，并将解析后的用户信息存入 `UserContext`。

### 引入依赖

```xml
<dependency>
    <groupId>cn.bs</groupId>
    <artifactId>tokenx-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>
```

### 配置

```yaml
cn:
  smart:
    tokenx:
      enable: true                                    # 启用 Token 验证（默认关闭）
      key: your-jwt-secret-key                        # JWT 签名密钥（HS256）
      path-patterns: /api/**                          # 拦截路径（默认 /api/**）
      exclude-path-patterns: /api/login,/api/register # 排除路径（白名单，多个逗号分隔）
      order: 1                                        # 拦截器顺序（默认 1）
```

### 配置属性说明

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `cn.smart.tokenx.enable` | boolean | `false` | 是否启用 Token 验证 |
| `cn.smart.tokenx.key` | String | - | JWT HS256 签名密钥 |
| `cn.smart.tokenx.path-patterns` | String | `/api/**` | 拦截器匹配路径（Ant 风格） |
| `cn.smart.tokenx.exclude-path-patterns` | String | - | 排除路径，多个逗号分隔 |
| `cn.smart.tokenx.order` | int | `1` | 拦截器排序 |

### 使用方式

Token 支持两种传递方式，优先取请求头 `token`，其次取 `Authorization: Bearer xxx`。

```java
@RestController
@RequestMapping("/api")
public class UserController {

    @GetMapping("/profile")
    public UserSession profile() {
        // Token 验证通过后，用户信息自动注入 UserContext
        return UserContext.get();
    }
}
```

**Token 验证规则：**

- 请求头 `token` 为空 -> 抛出 `BizException(403, "token不能为空")`
- Token 签名无效 -> 抛出 `BizException(403, "token不正确或失效")`
- Token 已过期 -> 抛出 `BizException(406, "token时间过期")`
- 验证通过 -> 解析 payload 到 `UserSession`，存入 `UserContext`

---

## xxl-jobx-spring-boot-starter - XXL-JOB 集成

XXL-JOB 分布式任务调度的 Spring Boot 自动配置 Starter，通过配置属性即可完成 Executor 注册。

### 引入依赖

```xml
<dependency>
    <groupId>cn.bs</groupId>
    <artifactId>xxl-jobx-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>
```

### 配置

```yaml
cn:
  smart:
    xxljobx:
      enable: true                                          # 启用 XXL-JOB（默认关闭）
      access-token: your-access-token                       # 与 Admin 通信的 Token
      admin:
        addresses: http://xxl-job-admin:8080/xxl-job-admin  # Admin 地址
      executor:
        appname: my-service                                 # 执行器名称
        port: 9999                                          # 执行器端口
        log-path: /data/applogs/xxl-job/jobhandler          # 日志路径
        log-retention-days: 30                              # 日志保留天数
```

### 配置属性说明

| 属性 | 类型 | 说明 |
|---|---|---|
| `cn.smart.xxljobx.enable` | boolean | 是否启用 |
| `cn.smart.xxljobx.access-token` | String | Admin 访问令牌 |
| `cn.smart.xxljobx.admin.addresses` | String | Admin 服务器地址 |
| `cn.smart.xxljobx.executor.appname` | String | 执行器应用名 |
| `cn.smart.xxljobx.executor.address` | String | 执行器地址（可选） |
| `cn.smart.xxljobx.executor.ip` | String | 执行器 IP（多网卡/容器场景使用） |
| `cn.smart.xxljobx.executor.port` | int | 执行器端口 |
| `cn.smart.xxljobx.executor.log-path` | String | 日志存储路径 |
| `cn.smart.xxljobx.executor.log-retention-days` | int | 日志保留天数 |

### 使用方式

配置完成后，按照 XXL-JOB 标准方式编写 JobHandler 即可：

```java
@Component
public class MyJobHandler {

    @XxlJob("demoJobHandler")
    public void demoJobHandler() throws Exception {
        XxlJobHelper.log("XXL-JOB, Hello World.");
        // 业务逻辑
    }
}
```

---

## common-feign-spring-boot-starter - Feign 响应解码

自定义 Feign 解码器 Starter，自动解包下游服务的 `ApiResponse` 格式响应，提取 `data` 字段作为返回值，非零 `code` 自动抛出 `BizException`。

### 引入依赖

```xml
<dependency>
    <groupId>cn.bs</groupId>
    <artifactId>common-feign-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>
```

### 配置

```yaml
cn:
  smart:
    decoderx:
      enable: true    # 默认已启用，设为 false 可关闭
```

> 注意：该 Starter 默认启用（`matchIfMissing = true`），无需显式配置即可生效。

### 使用方式

```java
@FeignClient(name = "user-service")
public interface UserFeignClient {

    @GetMapping("/api/users/{id}")
    User getUser(@PathVariable("id") Long id);
    // 下游返回: {"code":0, "data":{"id":1,"name":"张三"}, "msg":"ok"}
    // 解码后直接返回 User 对象
}
```

**解码规则：**

- `code == 0` 且 `data != null` -> 返回 `data` 反序列化后的对象
- `code == 0` 且 `data == null` -> 返回 `null`
- `code != 0` -> 抛出 `BizException(code, msg)`
- 非统一响应（普通 JSON、数组、文本、文件等）-> 委托 Spring Cloud 默认解码器按 Feign 方法声明类型处理

---

## 快速开始

### 1. 克隆源码并安装到本地仓库

```bash
git clone https://github.com/gem921/easy-starter.git
cd easy-starter
mvn clean install
```

执行后，所有 Starter 会被安装到你本地的 `~/.m2` 仓库，业务项目即可直接引入。

> 如需团队共享，可将构建产物部署到你自己的私有 Maven 仓库（Nexus / 阿里云 packages 等）：在根 `pom.xml` 中配置 `<distributionManagement>`，并在 `~/.m2/settings.xml` 中填入对应仓库的凭据后执行 `mvn clean deploy`。凭据请仅保存在本地 `settings.xml`，切勿提交到任何公开仓库。

### 2. 在业务项目中引入需要的 Starter

```xml
<dependencies>
    <!-- 统一响应包装 -->
    <dependency>
        <groupId>cn.bs</groupId>
        <artifactId>wapperx-spring-boot-starter</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>

    <!-- 自动分页 -->
    <dependency>
        <groupId>cn.bs</groupId>
        <artifactId>pagex-spring-boot-starter</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>

    <!-- 按需引入其他 Starter ... -->
</dependencies>
```

### 3. 在 application.yml 中开启所需功能

```yaml
cn:
  smart:
    wapperx:
      enable: true
    pagex:
      enable: true
    logtimex:
      enable: true
    tokenx:
      enable: true
      key: your-jwt-secret
```

---

## 启用状态一览

| Starter | 配置前缀 | 启用属性 | 默认状态 |
|---|---|---|---|
| pagex-spring-boot-starter | `cn.smart.pagex` | `enable=true` | 关闭 |
| wapperx-spring-boot-starter | `cn.smart.wapperx` | `enable=true` | 关闭 |
| logtimex-spring-boot-starter | `cn.smart.logtimex` | `enable=true` | 关闭 |
| tokenx-spring-boot-starter | `cn.smart.tokenx` | `enable=true` | 关闭 |
| xxl-jobx-spring-boot-starter | `cn.smart.xxljobx` | `enable=true` | 关闭 |
| common-feign-spring-boot-starter | `cn.smart.decoderx` | `enable=true` | **开启** |

---

## 贡献指南

欢迎任何形式的贡献，无论是提交 Issue、完善文档还是发起 Pull Request。

1. Fork 本仓库到你的账户。
2. 创建特性分支：`git checkout -b feature/your-feature`。
3. 提交改动：`git commit -m 'feat: 描述你的改动'`。
4. 推送分支：`git push origin feature/your-feature`。
5. 在 GitHub 上发起 Pull Request。

提交前请确保：

- 代码风格与现有模块保持一致。
- 新增能力补充对应的说明文档。
- 执行 `mvn clean install` 通过编译。

如果这个项目对你有帮助，欢迎点一个 Star 支持一下。

---

## 开源协议

本项目基于 [Apache License 2.0](LICENSE) 协议开源，可自由用于商业和非商业项目。