# hanggold-component

**Repository Path**: hanggold/hanggold-component

## Basic Information

- **Project Name**: hanggold-component
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-23
- **Last Updated**: 2025-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hanggold Component

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Maven Central](https://img.shields.io/maven-central/v/io.github.freedom-all/component.svg)](https://search.maven.org/artifact/io.github.freedom-all/component)
[![Java](https://img.shields.io/badge/Java-1.8+-green.svg)](https://www.oracle.com/java/technologies/)
[![Maven](https://img.shields.io/badge/Maven-3.6+-orange.svg)](https://maven.apache.org/)

悬金全部的基础组件库，提供验证码生成、MyBatis代码生成等常用功能组件。

## 📋 目录

- [项目介绍](#项目介绍)
- [功能特性](#功能特性)
- [快速开始](#快速开始)
- [模块说明](#模块说明)
- [API文档](#api文档)
- [配置说明](#配置说明)
- [示例代码](#示例代码)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

## 🚀 项目介绍

Hanggold Component 是一个基于 Java 8+ 的基础组件库，旨在为开发者提供高质量、易用的基础功能组件。项目采用 Maven 多模块架构，支持多种验证码生成方式和 MyBatis 代码自动生成功能。

### 项目结构

```
hanggold-component/
├── hanggold-captcha/          # 验证码组件
│   ├── src/main/java/
│   │   └── com/hanggold/captcha/
│   │       ├── core/          # 核心实现
│   │       ├── font/          # 字体服务
│   │       ├── util/          # 工具类
│   │       └── pojo/          # 数据对象
│   └── src/main/resources/
│       └── soul/family/       # 字体文件
├── hanggold-mybatis-gen/      # MyBatis代码生成组件
└── script/                    # 代码规范配置
```

## ✨ 功能特性

### 验证码组件 (hanggold-captcha)

- 🎨 **多种验证码类型**
  - 默认验证码：支持数字、字母混合
  - 中文验证码：支持中文字符
  - 算术验证码：支持数学运算
  - GIF动态验证码：支持动画效果

- 🎯 **丰富的配置选项**
  - 自定义字符集
  - 可配置干扰线和干扰圆
  - 支持多种字体
  - 灵活的尺寸和颜色配置

- 🔧 **易于集成**
  - 提供 Base64 和流输出两种方式
  - 支持 SPI 扩展机制
  - 完善的异常处理

### MyBatis代码生成组件 (hanggold-mybatis-gen)

- 📝 **自动生成基础SQL语句**
- 🔄 **支持多种数据库**
- ⚙️ **可配置生成规则**

## 🛠️ 快速开始

### 环境要求

- Java 1.8+
- Maven 3.6+

### 安装依赖

#### Maven

```xml
<dependency>
    <groupId>io.github.freedom-all</groupId>
    <artifactId>hanggold-captcha</artifactId>
    <version>0.0.2</version>
</dependency>
```

#### Gradle

```gradle
implementation 'io.github.freedom-all:hanggold-captcha:0.0.2'
```

### 基本使用

#### 1. 默认验证码

```java
import com.hanggold.captcha.Captcha;
import com.hanggold.captcha.core.impl.DefaultCaptcha;
import com.hanggold.captcha.pojo.CaptchaEntity;

// 创建验证码实例
Captcha captcha = new DefaultCaptcha();

// 生成Base64格式的验证码
CaptchaEntity entity = captcha.base64();
System.out.println("验证码值: " + entity.getValue());
System.out.println("Base64图片: " + entity.getBase64());

// 输出到流
try (OutputStream outputStream = new FileOutputStream("captcha.png")) {
    String value = captcha.write(outputStream);
    System.out.println("验证码值: " + value);
}
```

#### 2. 中文验证码

```java
import com.hanggold.captcha.core.impl.ChineseCaptcha;

Captcha chineseCaptcha = new ChineseCaptcha();
CaptchaEntity entity = chineseCaptcha.base64();
```

#### 3. 算术验证码

```java
import com.hanggold.captcha.core.impl.ArithmeticCaptcha;

Captcha arithmeticCaptcha = new ArithmeticCaptcha();
CaptchaEntity entity = arithmeticCaptcha.base64();
// 返回的是计算结果，如 "5" (对应 "2+3=?")
```

#### 4. GIF动态验证码

```java
import com.hanggold.captcha.core.impl.GifDefaultCaptcha;
import com.hanggold.captcha.core.impl.GifChineseCaptcha;
import com.hanggold.captcha.core.impl.GifArithmeticCaptcha;

// GIF默认验证码
Captcha gifCaptcha = new GifDefaultCaptcha();

// GIF中文验证码
Captcha gifChineseCaptcha = new GifChineseCaptcha();

// GIF算术验证码
Captcha gifArithmeticCaptcha = new GifArithmeticCaptcha();
```

## 📦 模块说明

### hanggold-captcha

验证码生成组件，提供多种类型的验证码生成功能。

#### 核心类

- `Captcha`: 验证码接口
- `CaptchaAbstract`: 抽象实现类
- `CaptchaEntity`: 验证码实体类

#### 实现类

- `DefaultCaptcha`: 默认验证码（数字字母混合）
- `ChineseCaptcha`: 中文验证码
- `ArithmeticCaptcha`: 算术验证码
- `GifDefaultCaptcha`: GIF默认验证码
- `GifChineseCaptcha`: GIF中文验证码
- `GifArithmeticCaptcha`: GIF算术验证码

#### 字体服务

- `FontStreamService`: 字体流服务接口
- `DefaultFontStreamService`: 默认字体服务
- `ChineseRegularScriptFontStreamService`: 中文楷体字体服务
- `ChineseSongFontStreamService`: 中文宋体字体服务
- `FounderYaoBodyFontStreamService`: 方正姚体字体服务

### hanggold-mybatis-gen

MyBatis代码生成组件，用于自动生成基础的SQL语句。

## 📚 API文档

### Captcha 接口

```java
public interface Captcha {
    /**
     * 生成Base64格式的验证码
     * @return 验证码实体，包含值和Base64图片
     */
    CaptchaEntity base64();
    
    /**
     * 将验证码写入输出流
     * @param outputStream 输出流
     * @return 验证码值
     */
    String write(OutputStream outputStream);
    
    /**
     * 获取验证码字符
     * @return 验证码字符数组
     */
    default char[] alphas();
    
    /**
     * 获取标准字符（用于宽度计算）
     * @return 标准字符
     */
    default String standardWeightChar();
    
    /**
     * 获取图片类型
     * @return 图片类型
     */
    default int imageType();
}
```

### CaptchaEntity 类

```java
public class CaptchaEntity {
    private String value;    // 验证码值
    private String base64;   // Base64格式的图片
    
    // 构造函数、getter、setter
}
```

## ⚙️ 配置说明

### 系统属性配置

可以通过系统属性自定义验证码的默认配置：

```bash
# 验证码字符数量
-Dsoul.captcha.count=4

# 验证码宽度
-Dsoul.captcha.weight=160

# 验证码高度
-Dsoul.captcha.height=60

# 字体大小
-Dsoul.captcha.font.size=32

# 干扰圆数量
-Dsoul.captcha.disturb.circle.count=4

# 干扰线数量
-Dsoul.captcha.disturb.lines.count=4

# GIF帧数
-Dsoul.captcha.gif.count=5

# GIF延迟时间
-Dsoul.captcha.gif.delay.time=300

# 字体文件路径
-Dsoul.font.family=/path/to/fonts
```

### 默认配置值

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 验证码字符数量 | 4 | 验证码包含的字符数量 |
| 验证码宽度 | 160 | 验证码图片宽度（像素） |
| 验证码高度 | 60 | 验证码图片高度（像素） |
| 字体大小 | 32 | 验证码字符字体大小 |
| 干扰圆数量 | 4 | 干扰圆的数量 |
| 干扰线数量 | 4 | 干扰线的数量 |
| GIF帧数 | 5 | GIF动画的帧数 |
| GIF延迟时间 | 300 | GIF帧间延迟时间（毫秒） |

## 💡 示例代码

### Web应用集成示例

```java
@RestController
@RequestMapping("/captcha")
public class CaptchaController {
    
    @GetMapping("/generate")
    public CaptchaEntity generateCaptcha() {
        Captcha captcha = new DefaultCaptcha();
        return captcha.base64();
    }
    
    @GetMapping("/chinese")
    public CaptchaEntity generateChineseCaptcha() {
        Captcha captcha = new ChineseCaptcha();
        return captcha.base64();
    }
    
    @GetMapping("/arithmetic")
    public CaptchaEntity generateArithmeticCaptcha() {
        Captcha captcha = new ArithmeticCaptcha();
        return captcha.base64();
    }
    
    @GetMapping("/gif")
    public void generateGifCaptcha(HttpServletResponse response) throws IOException {
        Captcha captcha = new GifDefaultCaptcha();
        response.setContentType("image/gif");
        captcha.write(response.getOutputStream());
    }
}
```

### 自定义验证码示例

```java
public class CustomCaptcha extends CaptchaAbstract {
    
    @Override
    public char[] alphas() {
        // 自定义字符集
        String chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < count(); i++) {
            sb.append(chars.charAt(randomInt(chars.length())));
        }
        return sb.toString().toCharArray();
    }
    
    @Override
    public void drawInterferenceLines(int count, int width, int height, Graphics2D graphics2D) {
        // 自定义干扰线绘制逻辑
        for (int i = 0; i < count; i++) {
            graphics2D.setColor(color());
            graphics2D.setStroke(new BasicStroke(2.0f));
            int x1 = randomInt(width);
            int y1 = randomInt(height);
            int x2 = randomInt(width);
            int y2 = randomInt(height);
            graphics2D.drawLine(x1, y1, x2, y2);
        }
    }
}
```

## 🤝 贡献指南

我们欢迎所有形式的贡献，包括但不限于：

- 🐛 Bug 报告
- 💡 功能建议
- 📝 文档改进
- 🔧 代码贡献

### 开发环境设置

1. Fork 项目
2. 克隆到本地
3. 安装依赖：`mvn clean install`
4. 运行测试：`mvn test`
5. 提交代码规范检查：`mvn checkstyle:check`

### 代码规范

项目使用 Checkstyle 进行代码规范检查，配置文件位于 `script/checkstyle.xml`。

### 提交规范

请遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具的变动

## 📄 许可证

本项目采用 [Apache License 2.0](LICENSE) 许可证。

## 📞 联系方式

- 项目地址：https://gitee.com/hanggold/hanggold-component
- 邮箱：sunmch420@gmail.com
- 组织：https://gitee.com/hanggold

## 🙏 致谢

感谢所有为这个项目做出贡献的开发者！

## 💝 项目起源

本项目最初源于在 Gitee 平台上看到的一个优秀的验证码实现项目。当时被其简洁而强大的设计所吸引，基于该项目的核心思想，结合自身特定需求进行了重新设计和实现。

虽然很遗憾未能找到原项目的具体地址，但在此特别感谢那位不知名的开源作者，正是您的创意和代码启发了这个项目的诞生。

**如果您是原项目的作者，欢迎通过以下方式联系我们：**
- 提交 Issue 或 Pull Request 到本项目
- 发送邮件至：sunmch420@gmail.com
- 在 Gitee 上联系：https://gitee.com/hanggold

我们非常乐意在项目中添加对您原项目的引用和感谢！

---

**注意**: 本项目仍在积极开发中，API可能会有变化。建议在生产环境使用前充分测试。