add article

internal/domains/api/services/processors/test/README.md

@@ -0,0 +1,94 @@
+# 测试处理器使用说明
+
+这个目录包含了用于测试的处理器，可以模拟各种API请求场景，帮助开发和测试人员验证系统功能。
+
+## 处理器列表
+
+### 1. ProcessTestRequest - 基础测试处理器
+- **功能**: 模拟正常的API请求处理
+- **用途**: 测试基本的请求处理流程、参数验证、响应生成等
+
+#### 请求参数
+```json
+{
+  "test_param": "测试参数值",
+  "delay": 1000
+}
+```
+
+#### 响应示例
+```json
+{
+  "message": "测试请求处理成功",
+  "timestamp": "2024-01-01T12:00:00Z",
+  "request_id": "test_20240101120000_000000000",
+  "test_param": "测试参数值",
+  "process_time_ms": 1005,
+  "status": "success"
+}
+```
+
+### 2. ProcessTestErrorRequest - 错误测试处理器
+- **功能**: 模拟各种错误情况
+- **用途**: 测试错误处理机制、异常响应等
+
+#### 支持的错误类型
+- `system_error`: 系统错误
+- `datasource_error`: 数据源错误
+- `not_found`: 资源未找到
+- `invalid_param`: 参数无效
+
+#### 请求示例
+```json
+{
+  "test_param": "system_error"
+}
+```
+
+### 3. ProcessTestTimeoutRequest - 超时测试处理器
+- **功能**: 模拟长时间处理导致的超时
+- **用途**: 测试超时处理、上下文取消等
+
+## 使用场景
+
+### 开发阶段
+- 验证处理器框架是否正常工作
+- 测试参数验证逻辑
+- 验证错误处理机制
+
+### 测试阶段
+- 性能测试（通过delay参数）
+- 超时测试
+- 错误场景测试
+- 集成测试
+
+### 调试阶段
+- 快速验证API调用流程
+- 测试中间件功能
+- 验证日志记录
+
+## 注意事项
+
+1. **延迟参数**: `delay` 参数最大值为5000毫秒（5秒），避免测试时等待时间过长
+2. **上下文处理**: 所有处理器都正确处理上下文取消，支持超时控制
+3. **错误处理**: 遵循项目的错误处理规范，使用预定义的错误类型
+4. **参数验证**: 使用标准的参数验证机制，确保测试的真实性
+
+## 集成到路由
+
+要将测试处理器集成到API路由中，需要在相应的路由配置中添加：
+
+```go
+// 在路由配置中添加测试端点
+router.POST("/api/test/basic", handlers.WrapProcessor(processors.ProcessTestRequest))
+router.POST("/api/test/error", handlers.WrapProcessor(processors.ProcessTestErrorRequest))
+router.POST("/api/test/timeout", handlers.WrapProcessor(processors.ProcessTestTimeoutRequest))
+```
+
+## 测试建议
+
+1. **基础功能测试**: 先使用 `ProcessTestRequest` 验证基本流程
+2. **错误场景测试**: 使用 `ProcessTestErrorRequest` 测试各种错误情况
+3. **性能测试**: 通过调整 `delay` 参数测试不同响应时间
+4. **超时测试**: 使用 `ProcessTestTimeoutRequest` 验证超时处理
+5. **压力测试**: 并发调用测试处理器的稳定性

internal/domains/api/services/processors/test/test_processor.go

@@ -0,0 +1,120 @@
+package test
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"time"
+
+	"tyapi-server/internal/domains/api/services/processors"
+)
+
+// TestRequest 测试请求参数
+type TestRequest struct {
+	TestParam string `json:"test_param" validate:"required"`
+	Delay     int    `json:"delay" validate:"min=0,max=5000"` // 延迟毫秒数，最大5秒
+}
+
+// TestResponse 测试响应数据
+type TestResponse struct {
+	Message     string    `json:"message"`
+	Timestamp   time.Time `json:"timestamp"`
+	RequestID   string    `json:"request_id"`
+	TestParam   string    `json:"test_param"`
+	ProcessTime int64     `json:"process_time_ms"`
+	Status      string    `json:"status"`
+}
+
+// ProcessTestRequest 测试处理器，用于模拟API请求
+func ProcessTestRequest(ctx context.Context, params []byte, deps *processors.ProcessorDependencies) ([]byte, error) {
+	startTime := time.Now()
+
+	// 解析请求参数
+	var req TestRequest
+	if err := json.Unmarshal(params, &req); err != nil {
+		return nil, errors.Join(processors.ErrInvalidParam, err)
+	}
+
+	// 参数验证
+	if err := deps.Validator.ValidateStruct(req); err != nil {
+		return nil, errors.Join(processors.ErrInvalidParam, err)
+	}
+
+	// 模拟处理延迟
+	if req.Delay > 0 {
+		select {
+		case <-ctx.Done():
+			return nil, errors.Join(processors.ErrSystem, ctx.Err())
+		case <-time.After(time.Duration(req.Delay) * time.Millisecond):
+			// 延迟完成
+		}
+	}
+
+	// 检查上下文是否已取消
+	if ctx.Err() != nil {
+		return nil, errors.Join(processors.ErrSystem, ctx.Err())
+	}
+
+	// 生成响应数据
+	response := TestResponse{
+		Message:     "测试请求处理成功",
+		Timestamp:   time.Now(),
+		RequestID:   generateTestRequestID(),
+		TestParam:   req.TestParam,
+		ProcessTime: time.Since(startTime).Milliseconds(),
+		Status:      "success",
+	}
+
+	// 序列化响应
+	result, err := json.Marshal(response)
+	if err != nil {
+		return nil, errors.Join(processors.ErrSystem, err)
+	}
+
+	return result, nil
+}
+
+// ProcessTestErrorRequest 测试错误处理的处理器
+func ProcessTestErrorRequest(ctx context.Context, params []byte, deps *processors.ProcessorDependencies) ([]byte, error) {
+	var req TestRequest
+	if err := json.Unmarshal(params, &req); err != nil {
+		return nil, errors.Join(processors.ErrInvalidParam, err)
+	}
+
+	// 模拟不同类型的错误
+	switch req.TestParam {
+	case "system_error":
+		return nil, processors.ErrSystem
+	case "datasource_error":
+		return nil, processors.ErrDatasource
+	case "not_found":
+		return nil, processors.ErrNotFound
+	case "invalid_param":
+		return nil, processors.ErrInvalidParam
+	default:
+		return nil, errors.Join(processors.ErrSystem, errors.New("未知错误类型"))
+	}
+}
+
+// ProcessTestTimeoutRequest 测试超时处理的处理器
+func ProcessTestTimeoutRequest(ctx context.Context, params []byte, deps *processors.ProcessorDependencies) ([]byte, error) {
+	var req TestRequest
+	if err := json.Unmarshal(params, &req); err != nil {
+		return nil, errors.Join(processors.ErrInvalidParam, err)
+	}
+
+	// 模拟长时间处理
+	select {
+	case <-ctx.Done():
+		return nil, errors.Join(processors.ErrSystem, ctx.Err())
+	case <-time.After(10 * time.Second): // 10秒超时
+		// 这里通常不会执行到，因为上下文会先超时
+	}
+
+	return nil, processors.ErrSystem
+}
+
+// generateTestRequestID 生成测试用的请求ID
+func generateTestRequestID() string {
+	return "test_" + time.Now().Format("20060102150405") + "_" + time.Now().Format("000000000")
+}