mirror of
https://github.com/chaitin/MonkeyCode.git
synced 2026-11-22 03:18:50 +08:00
Lifecycle Package
泛型化的生命周期管理框架,支持自定义状态类型和元数据。
架构说明
┌─────────────────────────────────────────┐
│ Manager[I, S, M] │
│ - Transition(ctx, id, to, metadata) │
│ - GetState(ctx, id) │
│ - Register(hooks...) │
└─────────────────────────────────────────┘
│
│ 触发
▼
┌─────────────────────────────────────────┐
│ Hook Pipeline │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Hook 1 │→│ Hook 2 │→│ Hook 3 │ │
│ │ (sync) │ │ (async) │ │ (async) │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────┘
核心组件
| 组件 | 说明 |
|---|---|
Manager[I, S, M] |
泛型生命周期管理器,I 为 ID 类型(comparable),S 为状态类型(基于 string),M 为元数据类型 |
Hook[I, S, M] |
生命周期钩子接口,支持同步/异步执行 |
State |
状态类型约束(~string,支持 string 及其派生类型) |
设计特点
- 完全泛型化: 支持任意
comparable的 ID 类型(string/uuid.UUID/int等)、任意基于string的状态类型、任意元数据类型 - Hook 链: 支持多个 Hook 按优先级排序执行(优先级数字越大越先执行)
- 异步支持: Hook 可配置为异步执行,不阻塞状态转换
- Redis 持久化: 状态和元数据存储使用 Redis Hash 结构
- 状态转换验证: 内置状态转换规则验证,防止非法状态跳转
使用示例
1. 定义状态类型和元数据
package lifecycle
// 任务状态
type TaskState string
const (
TaskStatePending TaskState = "pending"
TaskStateRunning TaskState = "running"
TaskStateFailed TaskState = "failed"
TaskStateSucceeded TaskState = "succeeded"
)
// 任务元数据
type TaskMetadata struct {
TaskID uuid.UUID `json:"task_id"`
UserID string `json:"user_id"`
}
2. 创建 Manager 并注册 Hooks
import "github.com/chaitin/MonkeyCode/backend/pkg/lifecycle"
// 创建 Manager(Task 用 uuid.UUID 作 ID)
taskMgr := lifecycle.NewManager[uuid.UUID, TaskState, TaskMetadata](
redisClient,
lifecycle.WithTransitions[uuid.UUID, TaskState, TaskMetadata](lifecycle.TaskTransitions()),
lifecycle.WithLogger(logger),
)
// 注册 Hooks(按优先级自动排序)
taskMgr.Register(
lifecycle.NewTaskNotifyHook(notifyDispatcher, logger),
lifecycle.NewTaskCreateHook(redisClient, taskflowClient, logger),
)
3. 状态转换
ctx := context.Background()
// 执行状态转换:pending -> running
meta := TaskMetadata{
TaskID: taskID,
UserID: "user-456",
}
err := taskMgr.Transition(ctx, taskID, TaskStateRunning, meta)
if err != nil {
return err
}
// Hooks 自动触发(按优先级:TaskCreateHook -> TaskNotifyHook)
4. 获取当前状态
state, err := taskMgr.GetState(ctx, taskID)
if err != nil {
return err
}
Hook 接口定义
type Hook[I comparable, S State, M any] interface {
// Name 返回 Hook 名称
Name() string
// Priority 返回优先级(数字越大优先级越高,先执行)
Priority() int
// Async 返回是否异步执行
Async() bool
// OnStateChange 状态变更回调
OnStateChange(ctx context.Context, id I, from, to S, metadata M) error
}
Hook 实现示例
type TaskNotifyHook struct {
notify *dispatcher.Dispatcher
logger *slog.Logger
}
func (h *TaskNotifyHook) Name() string { return "task-notify-hook" }
func (h *TaskNotifyHook) Priority() int { return 50 }
func (h *TaskNotifyHook) Async() bool { return true }
func (h *TaskNotifyHook) OnStateChange(ctx context.Context, taskID uuid.UUID, from, to TaskState, meta TaskMetadata) error {
// 发送通知逻辑
event := &NotifyEvent{
EventType: consts.NotifyEventTaskCompleted,
Payload: map[string]any{"status": to, "task_id": taskID},
}
return h.notify.Publish(ctx, event)
}
状态转换规则
默认状态转换规则
Task 状态转换
| 当前状态 (from) | 允许转换到 (to) | 说明 |
|---|---|---|
| (空) | pending, running | 初始创建 |
| pending | running, failed | 待处理状态 |
| running | succeeded, failed | 执行中状态 |
| failed | running | 失败可重试 |
| succeeded | (无) | 终态 |
VM 状态转换
| 当前状态 (from) | 允许转换到 (to) | 说明 |
|---|---|---|
| (空) | pending, creating | 初始创建 |
| pending | creating, failed | 待处理状态 |
| creating | running, failed | 创建中状态 |
| running | succeeded, failed | 运行中状态 |
| failed | running | 失败可重试 |
| succeeded | (无) | 终态 |
状态转换流程图
Task 生命周期:
(empty)
│
├─────────────┐
▼ ▼
pending running
│ │
│ ├─────────────┐
▼ ▼ ▼
running succeeded failed
│ │
├─────────────┐ │
▼ ▼ │
succeeded failed ──────────┘
VM 生命周期:
(empty)
│
├─────────────┐
▼ ▼
pending creating
│ │
│ ├─────────────┐
▼ ▼ ▼
creating running failed
│ │ │
│ ├─────────────┤
▼ ▼ │
succeeded failed ───────────┘
自定义状态转换
使用 WithTransitions 选项自定义状态转换规则:
// 订单状态示例
type OrderState string
const (
OrderStatePending OrderState = "pending"
OrderStatePaid OrderState = "paid"
OrderStateShipped OrderState = "shipped"
OrderStateDelivered OrderState = "delivered"
)
customTransitions := map[OrderState][]OrderState{
OrderStatePending: {OrderStatePaid},
OrderStatePaid: {OrderStateShipped, OrderStateRefunded},
OrderStateShipped: {OrderStateDelivered},
OrderStateDelivered: {},
}
mgr := lifecycle.NewManager[string, OrderState, OrderMetadata](
redisClient,
lifecycle.WithTransitions(customTransitions),
)
内置 Hook
Task 相关 Hooks
| Hook | 说明 | 优先级 | 执行方式 |
|---|---|---|---|
TaskNotifyHook |
任务状态变更时发送通知 | 50 | 异步 |
TaskCreateHook |
TaskStateRunning 时从 Redis 读取 CreateTaskReq 创建 taskflow 任务 | 80 | 同步 |
VM 相关 Hooks
| Hook | 说明 | 优先级 | 执行方式 |
|---|---|---|---|
VMTaskHook |
VM 状态变更时更新关联任务状态 | 100 | 同步 |
VMNotifyHook |
VM 状态变更时发送通知 | 50 | 异步 |
Hook 执行顺序示例
当 VM 状态变为 Running 时:
1. VMTaskHook (Priority=100, sync)
└─→ 更新任务状态为 Processing
2. TaskCreateHook (Priority=80, sync)
└─→ 从 Redis 读取 CreateTaskReq,创建 taskflow 任务
3. VMNotifyHook (Priority=50, async)
└─→ 发送 VMReady 通知
典型使用场景:任务 + VM 生命周期管理
完整流程
1. TaskUsecase.Create()
├─ 创建任务记录(数据库)
├─ 创建 VM(taskflow)
├─ 存储 CreateTaskReq 到 Redis(按 task.create_req_ttl_seconds 配置过期,默认 10 分钟)
│ key: task:create_req:{taskID}
├─ taskMgr.Transition(taskID, TaskStatePending, meta)
└─ vmMgr.Transition(vmID, VMStatePending, meta)
2. VM 就绪(InternalHandler.VmReady)
└─ vmMgr.Transition(vmID, VMStateRunning, meta)
├─ VMTaskHook: 更新任务状态为 Processing
├─ TaskCreateHook: 从 Redis 读取 CreateTaskReq → 创建 taskflow 任务 → 删除 key
└─ VMNotifyHook: 发送 VMReady 通知
3. 任务完成
└─ taskMgr.Transition(taskID, TaskStateSucceeded, meta)
└─ TaskNotifyHook: 发送 TaskCompleted 通知
代码示例
// 创建任务
func (a *TaskUsecase) Create(ctx context.Context, user *domain.User, req domain.CreateTaskReq, token string) (*domain.ProjectTask, error) {
// 1. 创建任务记录
pt, err := a.repo.Create(ctx, user, req, token, func(...) {
// 2. 创建 VM
vm := a.taskflow.VirtualMachiner().Create(...)
// 3. 临时存储 CreateTaskReq(按 task.create_req_ttl_seconds 配置过期)
reqKey := fmt.Sprintf("task:create_req:%s", task.ID)
a.redis.Set(ctx, reqKey, createReq, createReqTTL(a.cfg))
// 4. 初始化状态(Transition 会自动触发 Hook)
taskMeta := lifecycle.TaskMetadata{TaskID: t.ID, UserID: user.ID.String()}
a.taskLifecycle.Transition(ctx, t.ID, lifecycle.TaskStatePending, taskMeta)
vmMeta := lifecycle.VMMetadata{VMID: vm.ID, TaskID: t.ID.String(), UserID: user.ID.String()}
a.vmLifecycle.Transition(ctx, vm.ID, lifecycle.VMStatePending, vmMeta)
return vm, nil
})
return pt, nil
}
// VM 就绪回调
func (h *InternalHandler) VmReady(vmID string) error {
// 转换 VM 状态,自动触发 Hook 链
meta := lifecycle.VMMetadata{...}
return h.vmLifecycle.Transition(ctx, vmID, lifecycle.VMStateRunning, meta)
}
API 参考
Manager 方法
| 方法 | 签名 | 说明 |
|---|---|---|
NewManager |
func NewManager[I comparable, S State, M any](redis *redis.Client, opts ...Opt) *Manager[I, S, M] |
创建生命周期管理器 |
Transition |
func (m *Manager) Transition(ctx context.Context, id I, to S, metadata M) error |
执行状态转换(触发 Hook 链) |
GetState |
func (m *Manager) GetState(ctx context.Context, id I) (S, error) |
获取当前状态 |
Register |
func (m *Manager[I, S, M]) Register(hooks ...Hook[I, S, M]) |
注册 Hook(按优先级自动排序) |
配置选项
| 选项 | 签名 | 说明 |
|---|---|---|
WithLogger |
func WithLogger[I, S, M](logger *slog.Logger) Opt[I, S, M] |
设置日志器 |
WithTransitions |
func WithTransitions[I, S, M](transitions map[S][]S) Opt[I, S, M] |
设置状态转换规则 |
内置工具函数
| 函数 | 签名 | 说明 |
|---|---|---|
TaskTransitions |
func TaskTransitions() map[TaskState][]TaskState |
获取 Task 默认状态转换规则 |
VMTransitions |
func VMTransitions() map[VMState][]VMState |
获取 VM 默认状态转换规则 |
Redis 存储结构
Key: lifecycle:{id}
Type: Hash
Fields:
- state: 当前状态(string)
- from_state: 前一个状态(string)
- updated_at: 更新时间戳(毫秒)
示例:
lifecycle:task-uuid-123
state: "running"
from_state: "pending"
updated_at: 1710891245678
注意: 元数据(metadata)目前未持久化存储,由调用方通过 Transition 方法传入,供 Hook 使用。
类型定义
TaskState
type TaskState string
const (
TaskStatePending TaskState = "pending"
TaskStateRunning TaskState = "running"
TaskStateFailed TaskState = "failed"
TaskStateSucceeded TaskState = "succeeded"
)
VMState
type VMState string
const (
VMStatePending VMState = "pending"
VMStateCreating VMState = "creating"
VMStateRunning VMState = "running"
VMStateFailed VMState = "failed"
VMStateSucceeded VMState = "succeeded"
)
TaskMetadata
type TaskMetadata struct {
TaskID uuid.UUID `json:"task_id"`
UserID string `json:"user_id"`
}
VMMetadata
type VMMetadata struct {
VMID string `json:"vm_id"`
TaskID string `json:"task_id"`
UserID string `json:"user_id"`
}
测试
运行单元测试:
go test ./pkg/lifecycle/... -v
运行集成测试:
go test ./pkg/lifecycle/... -v -run Integration
运行特定 Hook 测试:
go test ./pkg/lifecycle/... -v -run TestTaskCreateHook