package/go-captcha
1
0
Fork 0
mirror of https://github.com/wenlng/go-captcha.git synced 2025-09-26 20:11:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md (#39)

Browse Source
This commit is contained in:
Awen
2025-05-19 00:53:58 +08:00
committed by GitHub
parent e284ca784b
commit c99dc26bb0
8 changed files with 217 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
README.md
View File

@@ -14,7 +14,7 @@
> English | [中文](README_zh.md)
<p style="text-align: center"><a href="https://github.com/wenlng/go-captcha">GoCaptcha</a> is a powerful, modular, and highly customizable behavioral CAPTCHA library that supports multiple interactive CAPTCHA types: Click, Slide, Drag, and Rotate.</p>
<p style="text-align: center"><a href="https://github.com/wenlng/go-captcha">GoCaptcha</a> is a powerful, modular, and highly customizable behavioral CAPTCHA library that supports multiple interactive CAPTCHA types: Click, Slide, Drag-Drop, and Rotate.</p>
<p style="text-align: center"> ⭐️ If it helps you, please give a star.</p>
@@ -64,9 +64,9 @@
`go-captcha` supports the following four CAPTCHA types, each with unique interaction methods, generation logic, and application scenarios:
1. **Click CAPTCHA**: Users click specified points or characters on the main image, supporting text and graphic modes.
2. **Slide CAPTCHA**: Users slide a puzzle piece to the correct position on the main image, supporting basic and drag modes.
3. **Rotate CAPTCHA**: Users rotate a thumbnail to align with the main image’s angle.
4. **Drag-Drop CAPTCHA**: A variant of the Slide CAPTCHA, allowing users to drag a puzzle piece to a target position within a larger range.
2. **Slide CAPTCHA**: Users slide a puzzle piece to the correct position on the main image, supporting basic and drag-drop modes.
3. **Drag-Drop CAPTCHA**: A variant of the Slide CAPTCHA, allowing users to drag-drop a puzzle piece to a target position within a larger range.
4. **Rotate CAPTCHA**: Users rotate a thumbnail to align with the main image’s angle.
<br/>
@@ -220,56 +220,72 @@ func main() {
### Make Instance
- builder.Make()
- builder.MakeWithShape()
- builder.MakeShape()
### Configuration Options
> click.NewBuilder(click.WithXxx(), ...) OR builder.SetOptions(click.WithXxx(), ...)
| Options | Desc |
|--------------------------------------------|---------------------------------------------|
| Master Image | |
| click.WithImageSize(option.Size) | default 300x220 |
| click.WithRangeLen(option.RangeVal) | |
| click.WithRangeAnglePos([]option.RangeVal) | |
| click.WithRangeSize(option.RangeVal) | |
| click.WithRangeColors([]string) | |
| click.WithDisplayShadow(bool) | |
| click.WithShadowColor(string) | |
| click.WithShadowPoint(option.Point) | |
| click.WithImageAlpha(float32) | |
| click.WithUseShapeOriginalColor(bool) | |
| Thumbnail Image |
| click.WithThumbImageSize(option.Size) | default 150x40 |
| click.WithRangeVerifyLen(option.RangeVal) | |
| click.WithDisabledRangeVerifyLen(bool) | |
| click.WithRangeThumbSize(option.RangeVal) | |
| click.WithRangeThumbColors([]string) | |
| click.WithRangeThumbBgColors([]string) | |
| click.WithIsThumbNonDeformAbility(bool) | |
| click.WithThumbBgDistort(int) | option.DistortLevel1 ~ option.DistortLevel5 |
| click.WithThumbBgCirclesNum(int) | |
| click.WithThumbBgSlimLineNum(int) | |
| Options | Desc |
|--------------------------------------------|------------------------------------------------------------------------------------|
| **Main Image** | |
| click.WithImageSize(option.Size) | Set main image size, default 300x220 |
| click.WithRangeLen(option.RangeVal) | Set range for random content length |
| click.WithRangeAnglePos([]option.RangeVal) | Set range for random angles |
| click.WithRangeSize(option.RangeVal) | Set range for random content size |
| click.WithRangeColors([]string) | Set random colors |
| click.WithDisplayShadow(bool) | Enable/disable shadow display |
| click.WithShadowColor(string) | Set shadow color |
| click.WithShadowPoint(option.Point) | Set shadow offset position |
| click.WithImageAlpha(float32) | Set main image transparency |
| click.WithUseShapeOriginalColor(bool) | Use original graphic color (valid for graphic mode) |
| **Thumbnail** | |
| click.WithThumbImageSize(option.Size) | Set thumbnail size, default 150x40 |
| click.WithRangeVerifyLen(option.RangeVal) | Set range for random verification content length |
| click.WithDisabledRangeVerifyLen(bool) | Disable random verification length, matches main content |
| click.WithRangeThumbSize(option.RangeVal) | Set range for random thumbnail content size |
| click.WithRangeThumbColors([]string) | Set range for random thumbnail colors |
| click.WithRangeThumbBgColors([]string) | Set range for random thumbnail background colors |
| click.WithIsThumbNonDeformAbility(bool) | Prevent thumbnail content deformation |
| click.WithThumbBgDistort(int) | Set thumbnail background distortion (option.DistortLevel1 to option.DistortLevel5) |
| click.WithThumbBgCirclesNum(int) | Set number of small circles in thumbnail background |
| click.WithThumbBgSlimLineNum(int) | Set number of lines in thumbnail background |
### Set Resources
> builder.SetResources(click.WithXxx(), ...)
| Options | Desc |
|-------------------------------------------|------|
| click.WithChars([]string) | |
| click.WithShapes(map[string]image.Image) | |
| click.WithFonts([]*truetype.Font) | |
| click.WithBackgrounds([]image.Image) | |
| click.WithThumbBackgrounds([]image.Image) | |
| Options | Desc |
|-------------------------------------------|----------------------------|
| click.WithChars([]string) | Set text seed |
| click.WithShapes(map[string]image.Image) | Set graphic seed |
| click.WithFonts([]*truetype.Font) | Set fonts |
| click.WithBackgrounds([]image.Image) | Set main image backgrounds |
| click.WithThumbBackgrounds([]image.Image) | Set thumbnail backgrounds |
### Captcha Data
> captData, err := capt.Generate()
| Method | Desc |
|------------------------------------------|------|
| GetData() map[int]*Dot | |
| GetMasterImage() imagedata.JPEGImageData | |
| GetThumbImage() imagedata.PNGImageData | |
| Method | Desc |
|------------------------------------------|-----------------------|
| GetData() map[int]*Dot | Get verification data |
| GetMasterImage() imagedata.JPEGImageData | Get main image |
| GetThumbImage() imagedata.PNGImageData | Get thumbnail |
### Validate the captcha
> ok := click.Validate(srcX, srcY, X, Y, width, height, paddingValue)
| Params | Desc |
|--------------|-----------------------|
| srcX | User X-axis |
| srcY | User Y-axis |
| X | X-axis |
| Y | Y-axis |
| width | Width |
| height | Height |
| paddingValue | Set the padding value |
<br/>
### Notes
@@ -280,7 +296,7 @@ func main() {
<br />
## 🖖 Slide CAPTCHA
## 🖖 Slide Or Drag-Drop CAPTCHA
The Slide CAPTCHA requires users to slide a puzzle piece to the correct position on the main image. It supports two modes:
@@ -415,40 +431,54 @@ func loadPng(p string) (image.Image, error) {
### Make Instance
- builder.Make()
- builder.MakeWithRegion()
- builder.MakeDragDrop()
### Configuration Options
> slide.NewBuilder(slide.WithXxx(), ...) OR builder.SetOptions(slide.WithXxx(), ...)
| Options | Desc |
|----------------------------------------------------------------|-----------------|
| slide.WithImageSize(*option.Size) | default 300x220 |
| slide.WithImageAlpha(float32) | |
| slide.WithRangeGraphSize(val option.RangeVal) | |
| slide.WithRangeGraphAnglePos([]option.RangeVal) | |
| slide.WithGenGraphNumber(val int) | |
| slide.WithEnableGraphVerticalRandom(val bool) | |
| slide.WithRangeDeadZoneDirections(val []DeadZoneDirectionType) | |
| Options | Desc |
|----------------------------------------------------------------|------------------------------------------------|
| slide.WithImageSize(*option.Size) | Set main image size, default 300x220 |
| slide.WithImageAlpha(float32) | Set main image transparency |
| slide.WithRangeGraphSize(val option.RangeVal) | Set range for random graphic size |
| slide.WithRangeGraphAnglePos([]option.RangeVal) | Set range for random graphic angles |
| slide.WithGenGraphNumber(val int) | Set number of graphics |
| slide.WithEnableGraphVerticalRandom(val bool) | Enable/disable random vertical graphic sorting |
| slide.WithRangeDeadZoneDirections(val []DeadZoneDirectionType) | Set dead zone directions for puzzle pieces |
### Set Resources
> builder.SetResources(slide.WithXxx(), ...)
| Options | Desc |
|-----------------------------------------------|------|
| slide.WithBackgrounds([]image.Image) | |
| slide.WithGraphImages(images []*GraphImage) | |
| Options | Desc |
|-----------------------------------------------|----------------------------|
| slide.WithBackgrounds([]image.Image) | Set main image backgrounds |
| slide.WithGraphImages(images []*GraphImage) | Set puzzle piece graphics |
### Captcha Data
> captData, err := capt.Generate()
| Method | Desc |
|------------------------------------------|------|
| GetData() *Block | |
| GetMasterImage() imagedata.JPEGImageData | |
| GetTileImage() imagedata.PNGImageData | |
| Method | Desc |
|------------------------------------------|-----------------------|
| GetData() *Block | Get verification data |
| GetMasterImage() imagedata.JPEGImageData | Get main image |
| GetTileImage() imagedata.PNGImageData | Get tile image |
### Validate the captcha
> ok := slide.Validate(srcX, srcY, X, Y, paddingValue)
| Params | Desc |
|--------------|-----------------------|
| srcX | User X-axis |
| srcY | User Y-axis |
| X | X-axis |
| Y | Y-axis |
| paddingValue | Set the padding value |
<br/>
### Notes
@@ -566,29 +596,40 @@ func loadPng(p string) (image.Image, error) {
### Configuration Options
> rotate.NewBuilder(rotate.WithXxx(), ...) OR builder.SetOptions(rotate.WithXxx(), ...)
| Options | Desc |
|--------------------------------------------------|-----------------|
| rotate.WithImageSquareSize(val int) | default 220x220 |
| rotate.WithRangeAnglePos(vals []option.RangeVal) | |
| rotate.WithRangeThumbImageSquareSize(val []int) | |
| rotate.WithThumbImageAlpha(val float32) | |
| Options | Desc |
|--------------------------------------------------|------------------------------------------|
| rotate.WithImageSquareSize(val int) | Set main image size, default 220x220 |
| rotate.WithRangeAnglePos(vals []option.RangeVal) | Set range for random verification angles |
| rotate.WithRangeThumbImageSquareSize(val []int) | Set thumbnail size |
| rotate.WithThumbImageAlpha(val float32) | Set thumbnail transparency |
### Set Resources
> builder.SetResources(rotate.WithXxx(), ...)
| Options | Desc |
|--------------------------------------------|------|
| rotate.WithBackgrounds([]image.Image) | |
| Options | Desc |
|--------------------------------------------|----------------------------|
| rotate.WithImages([]image.Image) | Set main image backgrounds |
### Captcha Data
> captData, err := capt.Generate()
| Method | Desc |
|------------------------------------------|------|
| GetData() *Block | |
| GetMasterImage() imagedata.JPEGImageData | |
| GetTileImage() imagedata.PNGImageData | |
| Method | Desc |
|------------------------------------------|-----------------------|
| GetData() *Block | Get verification data |
| GetMasterImage() imagedata.PNGImageData | Get main image |
| GetThumbImage() imagedata.PNGImageData | Get thumbnail |
### Validate the captcha
> ok := rotate.Validate(srcAngle, angle, paddingValue)
| Params | Desc |
|--------------|-----------------------|
| srcAngle | User Angle |
| angle | Angle |
| paddingValue | Set the padding value |
<br/>
### Notes
@@ -653,10 +694,11 @@ func loadPng(p string) (image.Image, error) {
- [ ] Flutter App
- [ ] Android App
- [ ] IOS App
- ...
- [ ] ...
## Deployment Service
- [ ] Docker Image
- [x] Binary Program
- [x] Docker Image
- ...
<br/>

55
README_zh.md
View File

@@ -14,7 +14,7 @@
> [English](README.md) | 中文
<p style="text-align: center">
<a style="font-weight: bold" href="https://github.com/wenlng/go-captcha">Go Captcha</a> 是功能强大、模块化且高度可定制的行为式验证码库，支持多种交互式验证码类型：点选（Click）、滑动（Slide）、拖拽（Drag） 和 旋转（Rotate）。
<a style="font-weight: bold" href="https://github.com/wenlng/go-captcha">Go Captcha</a> 是功能强大、模块化且高度可定制的行为式验证码库，支持多种交互式验证码类型：点选（Click）、滑动（Slide）、拖拽（Drag-Drop） 和 旋转（Rotate）。
</p>
<p style="text-align: center"> ⭐️ 如果能帮助到你，请随手给点一个star</p>
@@ -68,8 +68,8 @@
`go-captcha` 支持以下四种验证码类型，每种类型具有独特的交互方式、生成逻辑和应用场景：
1. **点选验证码（Click）**：用户在主图像中点击指定的点或字符，支持文本模式和图形模式。
2. **滑动验证码（Slide）**：用户将拼图块滑动到主图像中的正确位置，支持基本模式和拖拽模式。
3. **旋转验证码（Rotate）**：用户旋转缩略图使其与主图像的角度对齐。
4. **拖拽验证码（DragDrop）**：滑动验证码的变体，允许用户在更大范围内拖动拼图块到目标位置。
3. **拖拽验证码（DragDrop）**：滑动验证码的变体，允许用户在更大范围内拖动拼图块到目标位置。
4. **旋转验证码（Rotate）**：用户旋转缩略图使其与主图像的角度对齐。
<br/>
@@ -235,7 +235,7 @@ func main() {
### 创建实例
- builder.Make() 中文文本、字母数字混合点选
- builder.MakeWithShape() 图形点选
- builder.MakeShape() 图形点选
### 配置选项
> click.NewBuilder(click.WithXxx(), ...) 或 builder.SetOptions(click.WithXxx(), ...)
@@ -287,6 +287,20 @@ func main() {
| GetMasterImage() imagedata.JPEGImageData | 获取主图 |
| GetThumbImage() imagedata.PNGImageData | 获取缩略图 |
### 验证码校验
> ok := click.Validate(srcX, srcY, X, Y, width, height, paddingValue)
| Params | Desc |
|--------------|--------------------|
| srcX | 用户交互的 X 值 |
| srcY | 用户交互的 Y 值 |
| X | 验证码校验的 X 值 |
| Y | 验证码校验的 Y 值 |
| width | 验证码校验的 Width 值 |
| height | 验证码校验的 Height 值 |
| paddingValue | 控制误差值 |
<br/>
### 注意事项
@@ -296,7 +310,7 @@ func main() {
<br />
## 🖖 滑动验证码（Slide）
## 🖖 滑动/拖拽验证码（Slide/Drag-Drop）
滑动验证码要求用户将拼图块滑动到主图像中的正确位置，支持两种模式：
@@ -428,7 +442,7 @@ func loadPng(p string) (image.Image, error) {
### 创建实例
- builder.Make() 滑动式
- builder.MakeWithRegion() 区域内拖拽式
- builder.MakeDragDrop() 区域内拖拽式
### 配置选项
@@ -464,6 +478,19 @@ func loadPng(p string) (image.Image, error) {
| GetTileImage() imagedata.PNGImageData | 获取缩略图 |
### 验证码校验
> ok := slide.Validate(srcX, srcY, X, Y, paddingValue)
| Params | Desc |
|--------------|-----------------|
| srcX | 用户交互的 X 值 |
| srcY | 用户交互的 Y 值 |
| X | 验证码校验的 X 值 |
| Y | 验证码校验的 Y 值 |
| paddingValue | 控制误差值 |
<br/>
### 注意事项
- 拼图块的图像资源（`OverlayImage`, `ShadowImage`, `MaskImage`）必须有效，否则会触发 `ImageTypeErr`, `ShadowImageTypeErr` 或 `MaskImageTypeErr`。
@@ -473,6 +500,7 @@ func loadPng(p string) (image.Image, error) {
<br />
## 🖖 旋转验证码（Rotate）
旋转验证码要求用户旋转缩略图使其与主图像的角度对齐，适合需要直观交互的场景。
@@ -604,6 +632,18 @@ func loadPng(p string) (image.Image, error) {
| GetMasterImage() imagedata.JPEGImageData | 获取主图 |
| GetTileImage() imagedata.PNGImageData | 获取缩略图 |
### 验证码校验
> ok := rotate.Validate(srcAngle, angle, paddingValue)
| Params | Desc |
|--------------|-------|
| srcAngle | 用户交互的角度 |
| angle | 验证码校验的角度 |
| paddingValue | 控制误差值 |
<br/>
### 注意事项
- 背景图像不能为空，否则会触发 `EmptyImageErr`。
@@ -687,7 +727,8 @@ func loadPng(p string) (image.Image, error) {
- ...
## Deployment Service
- [ ] Docker Image
- [x] Binary Program
- [x] Docker Image
- ...
<br/>

12
v2/click/click.go
View File

@@ -40,13 +40,13 @@ const (
var _ Captcha = (*captcha)(nil)
var (
EmptyShapesErr = errors.New("empty shapes")
EmptyCharacterErr = errors.New("empty character")
CharRangeLenErr = errors.New("character length must be large than to 'rangeLen.Max'")
ShapesRangeLenErr = errors.New("total number of shapes must be large than to 'rangeLen.Max'")
ShapesTypeErr = errors.New("shape must be is image type")
EmptyShapesErr = errors.New("no shapes provided")
EmptyCharacterErr = errors.New("no character provided")
CharRangeLenErr = errors.New("character length must be greater than rangeLen.Max")
ShapesRangeLenErr = errors.New("total number of shapes must be greater than rangeLen.Max")
ShapesTypeErr = errors.New("shape must be an image type")
EmptyBackgroundImageErr = errors.New("no background image")
ModeSupportErr = errors.New("mode not supported")
ModeSupportErr = errors.New("mode is not supported")
)
// captcha is the concrete implementation of the Captcha interface

15
v2/click/check.go → v2/click/validate.go
View File

@@ -10,7 +10,7 @@ import (
"math"
)
// CheckPoint checks if a click point is within the specified area
// Validate checks if a click point is within the specified area
// params:
// - sx, sy: Coordinates of the click point
// - dx, dy: Top-left coordinates of the target area
@@ -18,6 +18,19 @@ import (
// - padding: Padding of the area
//
// return: Whether the point is within the area
func Validate(sx, sy, dx, dy, width, height, padding int) bool {
newWidth := width + (padding * 2)
newHeight := height + (padding * 2)
newDx := int(math.Max(float64(dx), float64(dx-padding)))
newDy := int(math.Max(float64(dy), float64(dy-padding)))
return sx >= newDx &&
sx <= newDx+newWidth &&
sy >= newDy &&
sy <= newDy+newHeight
}
// Deprecated: As of 2.1.0, it will be removed, please use [click.Validate]
func CheckPoint(sx, sy, dx, dy, width, height, padding int64) bool {
newWidth := width + (padding * 2)
newHeight := height + (padding * 2)

2
v2/rotate/rotate.go
View File

@@ -29,7 +29,7 @@ var _ Captcha = (*captcha)(nil)
var (
EmptyImageErr = errors.New("no image")
ImageTypeErr = errors.New("image must be is image.Image type")
ImageTypeErr = errors.New("image must be of type image.Image")
)
// captcha is the concrete implementation of the Captcha interface

11
v2/rotate/check.go → v2/rotate/validate.go
View File

@@ -6,13 +6,22 @@
package rotate
// CheckAngle checks if the rotation angle is within the specified range
// Validate checks if the rotation angle is within the specified range
// params:
// - angle: Current angle
// - dAngle: Target angle
// - padding: Angle padding
//
// return: Whether within range
func Validate(angle, dAngle, padding int) bool {
minAngle := 360 - padding
maxAngle := 360 + padding
angle += dAngle
return angle >= minAngle && angle <= maxAngle
}
// Deprecated: As of 2.1.0, it will be removed, please use [rotate.Validate]
func CheckAngle(angle, dAngle, padding int64) bool {
minAngle := 360 - padding
maxAngle := 360 + padding

10
v2/slide/slide.go
View File

@@ -37,11 +37,11 @@ type Captcha interface {
var _ Captcha = (*captcha)(nil)
var (
GraphImageErr = errors.New("graph image is incorrect")
GenerateDataErr = errors.New("generate data failed")
ImageTypeErr = errors.New("tile image must be is image.Image type")
ShadowImageTypeErr = errors.New("tile shadow image must be is image.Image type")
MaskImageTypeErr = errors.New("tile shadow image must be is image.Image type")
GraphImageErr = errors.New("graph image is invalid")
GenerateDataErr = errors.New("data generation failed")
ImageTypeErr = errors.New("tile image must be of type image.Image")
ShadowImageTypeErr = errors.New("tile shadow image must be of type image.Image")
MaskImageTypeErr = errors.New("tile mask image must be of type image.Image")
EmptyBackgroundImageErr = errors.New("no background image")
)

15
v2/slide/check.go → v2/slide/validate.go
View File

@@ -6,7 +6,7 @@
package slide
// CheckPoint checks if the point position is within the specified range
// Validate checks if the point position is within the specified range
// params:
// - sx: Source X coordinate
// - sy: Source Y coordinate
@@ -15,6 +15,19 @@ package slide
// - padding: Padding
//
// return: Whether within range
func Validate(sx, sy, dx, dy, padding int) bool {
newX := padding * 2
newY := padding * 2
newDx := dx - padding
newDy := dy - padding
return sx >= newDx &&
sx <= newDx+newX &&
sy >= newDy &&
sy <= newDy+newY
}
// Deprecated: As of 2.1.0, it will be removed, please use [slide.Validate]
func CheckPoint(sx, sy, dx, dy, padding int64) bool {
newX := padding * 2
newY := padding * 2