mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-03 15:06:36 +08:00
解耦任务框架与业务任务
This commit is contained in:
ryan
@@ -12,10 +12,11 @@ description: "项目专用：当新增或修改 Asynq 异步任务、后台任
|
||||
新增或修改任务前，先快速查看这些文件，确认当前实现没有漂移：
|
||||
|
||||
- `internal/task/handler.go`: `TaskHandler`、`TaskResult`、可选 `PayloadValidator`。
|
||||
- `internal/task/constants.go`: Asynq 任务类型常量、Admin 任务类型常量、`TaskMeta`、`TaskParam`、`DispatchableTasks`。
|
||||
- `internal/task/constants.go`: 框架通用常量，如 `QueueDefault` 和 `DefaultMaxRetry`。
|
||||
- `internal/task/meta.go`: 框架任务元数据结构体（TaskParam、TaskMeta）及全局动态注册与查询接口。
|
||||
- `internal/task/executor.go`: `RegisterHandler`、`ValidateAndNormalizePayload`、`DispatchTask`、`RetryTask`、`ProcessTask`、`AppendLog`。
|
||||
- `internal/task/handlers/register.go`: 内置 handler 的统一注册点，Admin API 和 Worker 都依赖它。
|
||||
- `internal/task/worker/worker.go`: Asynq mux 路由和队列配置。
|
||||
- `internal/task/handlers/register.go`: 内置 handler 和元数据的统一注册点，Admin API 和 Worker 都依赖它。
|
||||
- `internal/task/worker/worker.go`: Asynq mux 动态路由分发和队列配置。
|
||||
- `internal/task/scheduler/scheduler.go`: Cron 调度。
|
||||
- `internal/apps/admin/task/routers.go`: Admin 下发、查询、详情、重试 API。
|
||||
- 现有参考：`internal/apps/upload/tasks.go`（无参数任务）、`internal/apps/user/tasks.go`（带参数任务）。
|
||||
@@ -34,10 +35,9 @@ Admin dispatch -> ValidateAndNormalizePayload -> DispatchTask
|
||||
|
||||
> 需要可复制的代码模板时，阅读 [references/CODE-EXAMPLES.md](references/CODE-EXAMPLES.md)。那里包含任务常量、无参数 handler、带参数 `PayloadValidator`、统一注册、Worker 路由、Cron 配置和测试示例。
|
||||
|
||||
1. 定义任务元数据。
|
||||
- 在 `internal/task/constants.go` 添加 Asynq task type 常量，例如 `upload:cleanup_unused`。
|
||||
- 添加 Admin 可下发 task type 常量，例如 `cleanup_unused_uploads`。
|
||||
- 在 `DispatchableTasks` 添加 `TaskMeta`，设置 `AsynqTask`、`Name`、`Description`、`MaxRetry`、`Queue`、`Retryable`。
|
||||
1. 定义任务元数据与常量。
|
||||
- 业务包常量与元数据：在对应业务模块的 `internal/apps/<module>/tasks.go` 中定义 Asynq 任务类型常量（如 `CleanupUnusedUploadsTask = "upload:cleanup_unused"`）和 Admin 任务类型常量（如 `TaskTypeCleanupUploads = "cleanup_unused_uploads"`）。
|
||||
- 在同一 `tasks.go` 文件中定义该任务的 `TaskMeta` 元数据变量（如 `CleanupUnusedUploadsMeta = task.TaskMeta{...}`），配置 `Type`、`AsynqTask`、`Name`、`Description`、`MaxRetry`、`Queue`、`Retryable` 等字段。
|
||||
- 有参数任务在 `Params` 中描述前端表单字段。`TaskParam.Name` 必须与 payload JSON tag 对齐。
|
||||
|
||||
2. 实现 handler。
|
||||
@@ -48,19 +48,16 @@ Admin dispatch -> ValidateAndNormalizePayload -> DispatchTask
|
||||
- 不要在 handler 中写复杂 SQL；复杂查询放到 `internal/model/` 或 `internal/service/`。
|
||||
- 新增 Go 文件后检查 license header；必要时运行 `make license`。
|
||||
|
||||
3. 统一注册 handler。
|
||||
- 在 `internal/task/handlers/register.go` 导入业务模块并调用 `task.RegisterHandler(asynqTaskType, handler)`。
|
||||
- 这里是 Admin payload 校验和 Worker 执行共同依赖的注册点。不要只在 worker 包里注册。
|
||||
3. 统一注册 handler 与元数据。
|
||||
- 在 `internal/task/handlers/register.go` 导入业务模块，调用 `task.RegisterHandler(asynqTaskType, handler)` 注册处理器。
|
||||
- 同时，在该文件中调用 `task.RegisterTaskMeta(meta)` 注册刚才在业务模块中定义的任务元数据。
|
||||
- 这里是 Admin 校验、元数据获取和 Worker 执行共同依赖的注册点。
|
||||
|
||||
4. 注册 Worker 路由。
|
||||
- 在 `internal/task/worker/worker.go` 的 Asynq mux 中添加 `mux.HandleFunc(task.YourAsynqTask, task.ProcessTask)`。
|
||||
- 所有业务任务都应交给 `task.ProcessTask`，由 executor 根据 task type 分发到 handler。
|
||||
|
||||
5. 如需 Cron 调度，系统默认定时任务必须通过 SQL 迁移（goose）初始化。
|
||||
- 确保任务在 `DispatchableTasks` 中已正确配置 `TaskMeta`。
|
||||
4. 如需 Cron 调度，系统默认定时任务必须通过 SQL 迁移（goose）初始化。
|
||||
- 确保任务已正确注册并载入全局元数据池中。
|
||||
- 在 `internal/db/migrator/goose/postgres` 和 `sqlite` 下编写 migration 脚本，使用 `INSERT INTO schedules` 语句初始化任务，指定 `task_type` 和 `cron` 等字段。必须妥善处理冲突（如 `ON CONFLICT DO NOTHING`）以支持幂等。
|
||||
|
||||
6. 如改动 Admin API。
|
||||
5. 如改动 Admin API。
|
||||
- handler 放在 `internal/apps/admin/<module>/` 或现有 Admin task 模块内。
|
||||
- 路由只在 `internal/router/router.go` 注册。
|
||||
- 响应保持 `{ "error_msg": "", "data": ... }`，分页保持 `{ "total": 0, "results": [] }`。
|
||||
|
||||
@@ -2,28 +2,33 @@
|
||||
|
||||
这些示例用于新增或修改 Wavelet Asynq 任务时快速套用。复制前先对照当前代码，因为任务框架可能随项目演进。
|
||||
|
||||
## 任务元数据
|
||||
## 任务元数据与常量定义
|
||||
|
||||
在 `internal/task/constants.go` 添加 Asynq task type、Admin task type 和 `TaskMeta`。
|
||||
在对应的业务包 `internal/apps/<module>/tasks.go` 中定义 Asynq task type、Admin task type 和 `TaskMeta`。
|
||||
|
||||
```go
|
||||
package upload
|
||||
|
||||
import (
|
||||
"github.com/Rain-kl/Wavelet/internal/task"
|
||||
)
|
||||
|
||||
// 异步任务类型标识。格式建议为 "{module}:{action}"。
|
||||
const CleanupUnusedUploadsTask = "upload:cleanup_unused"
|
||||
|
||||
// 管理员可下发的任务类型标识。用于 Admin API 的 task_type。
|
||||
const TaskTypeCleanupUploads = "cleanup_unused_uploads"
|
||||
|
||||
var DispatchableTasks = []TaskMeta{
|
||||
{
|
||||
Type: TaskTypeCleanupUploads,
|
||||
AsynqTask: CleanupUnusedUploadsTask,
|
||||
Name: "清理未使用上传",
|
||||
Description: "清理超过1小时未使用的上传文件",
|
||||
SupportsTime: false,
|
||||
MaxRetry: defaultMaxRetry,
|
||||
Queue: QueueDefault,
|
||||
Retryable: true,
|
||||
},
|
||||
// CleanupUnusedUploadsMeta 任务元数据
|
||||
var CleanupUnusedUploadsMeta = task.TaskMeta{
|
||||
Type: TaskTypeCleanupUploads,
|
||||
AsynqTask: CleanupUnusedUploadsTask,
|
||||
Name: "清理未使用上传",
|
||||
Description: "清理超过1小时未使用的上传文件",
|
||||
SupportsTime: false,
|
||||
MaxRetry: task.DefaultMaxRetry,
|
||||
Queue: task.QueueDefault,
|
||||
Retryable: true,
|
||||
}
|
||||
```
|
||||
|
||||
@@ -175,28 +180,6 @@ func Register() {
|
||||
}
|
||||
```
|
||||
|
||||
## Worker 路由
|
||||
|
||||
在 `internal/task/worker/worker.go` 的 mux 上添加任务类型。所有业务任务都指向 `task.ProcessTask`。
|
||||
|
||||
```go
|
||||
func StartWorker() error {
|
||||
asynqServer := asynq.NewServer(task.RedisOpt, asynq.Config{
|
||||
Concurrency: config.Config.Worker.Concurrency,
|
||||
ShutdownTimeout: workerShutdownTimeout,
|
||||
Queues: buildQueuesFromConfig(),
|
||||
StrictPriority: config.Config.Worker.StrictPriority,
|
||||
})
|
||||
|
||||
mux := asynq.NewServeMux()
|
||||
mux.Use(taskLoggingMiddleware)
|
||||
mux.HandleFunc(task.CleanupUnusedUploadsTask, task.ProcessTask)
|
||||
mux.HandleFunc(task.SendEmailTask, task.ProcessTask)
|
||||
|
||||
return asynqServer.Run(mux)
|
||||
}
|
||||
```
|
||||
|
||||
## Cron 调度和配置
|
||||
|
||||
系统默认的定时任务必须通过 Goose SQL 迁移初始化插入到 `schedules` 表。
|
||||
|
||||
Reference in New Issue
Block a user