# excel-export-starter

**Repository Path**: ForeverQAQ/excel-export-starter

## Basic Information

- **Project Name**: excel-export-starter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <img src="https://img.shields.io/badge/Excel-Export-brightgreen" alt="Excel Export" width="300" height="100"/>
</div>

<div align="center">

[![Java](https://img.shields.io/badge/Java-8%2B-blue)](https://adoptium.net)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.x%20%7C%203.x-blue)](https://spring.io/projects/spring-boot)
[![EasyExcel](https://img.shields.io/badge/EasyExcel-3.3.2-brightgreen)](https://github.com/alibaba/easyexcel)
[![License](https://img.shields.io/github/license/wuyuanQAQ/excel-export-starter)](https://github.com/wuyuanQAQ/excel-export-starter/blob/master/LICENSE)
[![Stars](https://img.shields.io/github/stars/wuyuanQAQ/excel-export-starter)](https://github.com/wuyuanQAQ/excel-export-starter/stargazers)
[![Forks](https://img.shields.io/github/forks/wuyuanQAQ/excel-export-starter)](https://github.com/wuyuanQAQ/excel-export-starter/network)

</div>

## 📖 介绍

**excel-export-starter** 是一款轻量级的 Excel 导出 Spring Boot Starter，基于 **AOP 切面** 和 **EasyExcel** 实现。通过注解即可轻松实现 Controller 层的 Excel 导出功能，同时兼容 **Spring Boot 2.x** 和 **Spring Boot 3.x**。

## ✨ 特性

- 🎯 **注解驱动**：只需在 Controller 方法添加 `@AutoExcelExport` 注解即可导出 Excel
- 🔍 **自动推断**：自动从方法返回值的泛型中推断 VO 类型
- 🔄 **双重兼容**：同时支持 Spring Boot 2.x（javax.servlet）和 3.x（jakarta.servlet）
- 🛡️ **无侵入**：基于 AOP 实现，不影响原有业务代码
- 📦 **开箱即用**：引入依赖即可使用，无需复杂配置

## 🛠️ 软件架构

```mermaid
graph TB
    subgraph "📦 核心层"
        AOP[@AutoExcelExport<br/>注解]
        ASPECT[ExcelExportAspect<br/>AOP 切面]
        RESOLVER[VoClassResolver<br/>VO 类型解析]
        WRITER[SimpleExcelWriter<br/>Excel 写入器]
    end

    subgraph "📚 依赖库"
        EASYEXCEL[EasyExcel<br/>阿里开源 Excel 处理库]
        SPRING_AOP[Spring AOP<br/>切面编程]
    end

    subgraph "🎯 使用层"
        CONTROLLER[Controller<br/>接口层]
        VO[VO 实体类<br/>带 @ExcelProperty 注解]
    end

    CONTROLLER --> AOP
    AOP --> ASPECT
    ASPECT --> RESOLVER
    ASPECT --> WRITER
    RESOLVER --> VO
    WRITER --> EASYEXCEL
    ASPECT --> SPRING_AOP

    style AOP fill:#e1f5fe
    style ASPECT fill:#f3e5f5
    style CONTROLLER fill:#e8f5e8
    style VO fill:#fff3e0
    style EASYEXCEL fill:#ffebee
```

## 🚀 快速开始

### 1. Maven 引入

Spring Boot 2.x（Java 8+）：
```xml
<dependency>
    <groupId>com.wuyuan</groupId>
    <artifactId>excel-export-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

Spring Boot 3.x（Java 17+）：
```xml
<dependency>
    <groupId>com.wuyuan</groupId>
    <artifactId>excel-export-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 在 VO 类字段上添加注解

```java
public class UserVO {
    @ExcelProperty(value = "姓名", index = 0)
    private String name;

    @ExcelProperty(value = "年龄", index = 1)
    private Integer age;

    @ExcelProperty(value = "邮箱", index = 2)
    private String email;
}
```

### 3. 在 Controller 方法上添加注解

```java
@AutoExcelExport(fileName = "用户列表")
@GetMapping("/export/users")
public ResultBean<List<UserVO>> exportUsers() {
    List<UserVO> users = userService.list();
    return ResultBean.success(users);
}
```

## 📜 注解说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| fileName | 导出文件名（必填） | - |
| sheetName | Sheet 名称 | 默认使用 fileName |
| excelClass | 指定 VO 类型 Class | 从泛型自动推断 |

## ⚠️ 注意事项

> [!IMPORTANT]
> - 方法返回值需要是 `ResultBean<List<T>>` 或 `List<T>>` 形式
> - 建议将导出方法名以 `export` 或 `download` 开头，避免与其他 AOP 冲突
> - VO 类的字段必须添加 `@ExcelProperty` 注解并指定 index

## 🤝 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 📄 License

本项目基于 [MIT License](LICENSE) 开源。