@robsun/create-keystone-app 0.2.12 → 0.2.15

package/template/.claude/skills/keystone-dev/references/ADVANCED_PATTERNS.md

@@ -0,0 +1,716 @@
+# Keystone 高级开发模式
+
+> 本文档补充复杂业务场景的设计模式和最佳实践。
+
+## 模块间依赖管理
+
+### 1. 跨模块服务调用
+
+当模块 A 需要调用模块 B 的服务时，通过依赖注入避免循环依赖。
+
+```go
+// apps/server/internal/app/container.go
+type Container struct {
+	OrderService   *order.OrderService
+	ProductService *product.ProductService
+	// ...
+}
+
+func NewContainer(db *gorm.DB) *Container {
+	// 先创建基础服务
+	productRepo := product.NewProductRepository(db)
+	productSvc := product.NewProductService(productRepo)
+
+	// 再创建依赖其他模块的服务
+	orderRepo := order.NewOrderRepository(db)
+	orderSvc := order.NewOrderService(orderRepo, productSvc) // 注入 productSvc
+
+	return &Container{
+		OrderService:   orderSvc,
+		ProductService: productSvc,
+	}
+}
+```
+
+### 2. 接口隔离原则
+
+在 Service 中只依赖需要的接口，而非整个服务：
+
+```go
+// order/domain/service/service.go
+package service
+
+// 只定义需要的方法接口
+type ProductPricer interface {
+	GetPrice(ctx context.Context, productID uint) (float64, error)
+}
+
+type OrderService struct {
+	repo   OrderRepository
+	pricer ProductPricer // 只依赖接口
+}
+
+func NewOrderService(repo OrderRepository, pricer ProductPricer) *OrderService {
+	return &OrderService{repo: repo, pricer: pricer}
+}
+```
+
+### 3. 事件驱动解耦
+
+对于松耦合场景，使用事件总线：
+
+```go
+// infra/events/bus.go
+type Event interface {
+	Name() string
+}
+
+type Handler func(ctx context.Context, event Event) error
+
+type Bus struct {
+	handlers map[string][]Handler
+	mu       sync.RWMutex
+}
+
+func (b *Bus) Subscribe(eventName string, handler Handler) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.handlers[eventName] = append(b.handlers[eventName], handler)
+}
+
+func (b *Bus) Publish(ctx context.Context, event Event) error {
+	b.mu.RLock()
+	handlers := b.handlers[event.Name()]
+	b.mu.RUnlock()
+
+	for _, h := range handlers {
+		if err := h(ctx, event); err != nil {
+			slog.Error("事件处理失败", "event", event.Name(), "error", err)
+		}
+	}
+	return nil
+}
+
+// 使用示例
+type OrderCreatedEvent struct {
+	OrderID   uint
+	TenantID  uint
+	Amount    float64
+	CreatedAt time.Time
+}
+
+func (e OrderCreatedEvent) Name() string { return "order.created" }
+
+// 在 Order 模块发布事件
+func (s *OrderService) Create(ctx context.Context, ...) (*Order, error) {
+	// ... 创建订单逻辑
+
+	s.bus.Publish(ctx, OrderCreatedEvent{
+		OrderID:   order.ID,
+		TenantID:  order.TenantID,
+		Amount:    order.TotalAmount,
+		CreatedAt: order.CreatedAt,
+	})
+
+	return order, nil
+}
+
+// 在 Statistics 模块订阅事件
+func (m *StatisticsModule) RegisterEventHandlers(bus *events.Bus) {
+	bus.Subscribe("order.created", func(ctx context.Context, e events.Event) error {
+		event := e.(OrderCreatedEvent)
+		return m.svc.UpdateDailyStats(ctx, event.TenantID, event.Amount)
+	})
+}
+```
+
+---
+
+## 状态机模式
+
+适用于有复杂状态流转的业务实体（订单、审批、工单等）。
+
+### 1. 状态机定义
+
+```go
+// domain/models/states.go
+package models
+
+type OrderStatus string
+
+const (
+	OrderStatusDraft     OrderStatus = "draft"
+	OrderStatusSubmitted OrderStatus = "submitted"
+	OrderStatusApproved  OrderStatus = "approved"
+	OrderStatusRejected  OrderStatus = "rejected"
+	OrderStatusPaid      OrderStatus = "paid"
+	OrderStatusShipped   OrderStatus = "shipped"
+	OrderStatusCompleted OrderStatus = "completed"
+	OrderStatusCancelled OrderStatus = "cancelled"
+)
+
+// 状态转换规则
+var orderTransitions = map[OrderStatus][]OrderStatus{
+	OrderStatusDraft:     {OrderStatusSubmitted, OrderStatusCancelled},
+	OrderStatusSubmitted: {OrderStatusApproved, OrderStatusRejected},
+	OrderStatusApproved:  {OrderStatusPaid, OrderStatusCancelled},
+	OrderStatusRejected:  {OrderStatusDraft},
+	OrderStatusPaid:      {OrderStatusShipped},
+	OrderStatusShipped:   {OrderStatusCompleted},
+}
+
+func (s OrderStatus) CanTransitionTo(target OrderStatus) bool {
+	allowed, exists := orderTransitions[s]
+	if !exists {
+		return false
+	}
+	for _, a := range allowed {
+		if a == target {
+			return true
+		}
+	}
+	return false
+}
+
+func (o *Order) TransitionTo(newStatus OrderStatus) error {
+	if !o.Status.CanTransitionTo(newStatus) {
+		return fmt.Errorf("无法从 %s 转换到 %s", o.Status, newStatus)
+	}
+	o.Status = newStatus
+	return nil
+}
+```
+
+### 2. 状态操作服务
+
+```go
+// domain/service/transitions.go
+package service
+
+func (s *OrderService) Submit(ctx context.Context, tenantID, id, userID uint) error {
+	return s.transition(ctx, tenantID, id, userID, models.OrderStatusSubmitted, nil)
+}
+
+func (s *OrderService) Approve(ctx context.Context, tenantID, id, userID uint) error {
+	return s.transition(ctx, tenantID, id, userID, models.OrderStatusApproved, nil)
+}
+
+func (s *OrderService) Reject(ctx context.Context, tenantID, id, userID uint, reason string) error {
+	return s.transition(ctx, tenantID, id, userID, models.OrderStatusRejected, func(o *models.Order) {
+		o.RejectReason = reason
+	})
+}
+
+func (s *OrderService) transition(
+	ctx context.Context,
+	tenantID, id, userID uint,
+	newStatus models.OrderStatus,
+	beforeSave func(*models.Order),
+) error {
+	order, err := s.repo.FindByID(tenantID, id)
+	if err != nil {
+		return err
+	}
+
+	oldStatus := order.Status
+	if err := order.TransitionTo(newStatus); err != nil {
+		return err
+	}
+
+	if beforeSave != nil {
+		beforeSave(order)
+	}
+
+	// 记录状态变更日志
+	log := &models.OrderStatusLog{
+		OrderID:   order.ID,
+		FromStatus: oldStatus,
+		ToStatus:   newStatus,
+		OperatorID: userID,
+		CreatedAt:  time.Now(),
+	}
+
+	return s.db.Transaction(func(tx *gorm.DB) error {
+		if err := tx.Save(order).Error; err != nil {
+			return err
+		}
+		return tx.Create(log).Error
+	})
+}
+```
+
+---
+
+## 多租户高级模式
+
+### 1. 自动租户过滤中间件
+
+```go
+// infra/middleware/tenant.go
+package middleware
+
+func TenantScope(db *gorm.DB) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		tenantID, ok := hcommon.GetTenantID(c)
+		if !ok {
+			response.Unauthorized(c, "租户信息缺失")
+			c.Abort()
+			return
+		}
+
+		// 创建带租户作用域的 DB 实例
+		scopedDB := db.Scopes(func(d *gorm.DB) *gorm.DB {
+			return d.Where("tenant_id = ?", tenantID)
+		})
+
+		// 存入 context
+		c.Set("scopedDB", scopedDB)
+		c.Next()
+	}
+}
+
+// 在 handler 中使用
+func GetScopedDB(c *gin.Context) *gorm.DB {
+	if db, ok := c.Get("scopedDB"); ok {
+		return db.(*gorm.DB)
+	}
+	return nil
+}
+```
+
+### 2. 租户数据隔离验证
+
+```go
+// 在 Repository 中添加验证
+func (r *Repository) FindByID(tenantID, id uint) (*models.Entity, error) {
+	var entity models.Entity
+	err := r.db.Where("id = ?", id).First(&entity).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, service.ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	// 验证租户归属
+	if entity.TenantID != tenantID {
+		slog.Warn("跨租户访问尝试",
+			"requestedTenant", tenantID,
+			"actualTenant", entity.TenantID,
+			"entityID", id,
+		)
+		return nil, service.ErrNotFound // 不暴露真实错误
+	}
+
+	return &entity, nil
+}
+```
+
+---
+
+## 缓存模式
+
+### 1. 读穿透缓存
+
+```go
+// infra/cache/cache.go
+package cache
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+type Cache struct {
+	client *redis.Client
+}
+
+func (c *Cache) GetOrLoad[T any](
+	ctx context.Context,
+	key string,
+	ttl time.Duration,
+	loader func() (T, error),
+) (T, error) {
+	var result T
+
+	// 尝试从缓存读取
+	data, err := c.client.Get(ctx, key).Bytes()
+	if err == nil {
+		if err := json.Unmarshal(data, &result); err == nil {
+			return result, nil
+		}
+	}
+
+	// 缓存未命中，加载数据
+	result, err = loader()
+	if err != nil {
+		return result, err
+	}
+
+	// 写入缓存
+	data, _ = json.Marshal(result)
+	c.client.Set(ctx, key, data, ttl)
+
+	return result, nil
+}
+
+// 使用示例
+func (s *ProductService) GetByID(ctx context.Context, tenantID, id uint) (*models.Product, error) {
+	key := fmt.Sprintf("product:%d:%d", tenantID, id)
+
+	return s.cache.GetOrLoad(ctx, key, 5*time.Minute, func() (*models.Product, error) {
+		return s.repo.FindByID(tenantID, id)
+	})
+}
+```
+
+### 2. 缓存失效策略
+
+```go
+// 更新时主动失效
+func (s *ProductService) Update(ctx context.Context, tenantID, id uint, input UpdateInput) (*models.Product, error) {
+	product, err := s.repo.Update(ctx, tenantID, id, input)
+	if err != nil {
+		return nil, err
+	}
+
+	// 删除缓存
+	key := fmt.Sprintf("product:%d:%d", tenantID, id)
+	s.cache.Delete(ctx, key)
+
+	// 发布缓存失效事件（用于分布式场景）
+	s.bus.Publish(ctx, CacheInvalidatedEvent{Key: key})
+
+	return product, nil
+}
+```
+
+---
+
+## 并发控制模式
+
+### 1. 分布式锁
+
+```go
+// infra/lock/redis.go
+package lock
+
+import (
+	"context"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+type RedisLock struct {
+	client *redis.Client
+}
+
+func (l *RedisLock) TryLock(ctx context.Context, key string, ttl time.Duration) (bool, error) {
+	return l.client.SetNX(ctx, "lock:"+key, "1", ttl).Result()
+}
+
+func (l *RedisLock) Unlock(ctx context.Context, key string) error {
+	return l.client.Del(ctx, "lock:"+key).Err()
+}
+
+// 使用示例：防止重复提交
+func (s *OrderService) Submit(ctx context.Context, tenantID, id, userID uint) error {
+	lockKey := fmt.Sprintf("order:submit:%d:%d", tenantID, id)
+
+	acquired, err := s.lock.TryLock(ctx, lockKey, 30*time.Second)
+	if err != nil {
+		return err
+	}
+	if !acquired {
+		return ErrOperationInProgress
+	}
+	defer s.lock.Unlock(ctx, lockKey)
+
+	// 执行提交逻辑
+	return s.doSubmit(ctx, tenantID, id, userID)
+}
+```
+
+### 2. 幂等性处理
+
+```go
+// infra/idempotency/store.go
+package idempotency
+
+type Store interface {
+	Check(ctx context.Context, key string) (exists bool, result interface{}, err error)
+	Save(ctx context.Context, key string, result interface{}, ttl time.Duration) error
+}
+
+// 使用示例
+func (h *Handler) Create(c *gin.Context) {
+	// 从请求头获取幂等键
+	idempotencyKey := c.GetHeader("X-Idempotency-Key")
+	if idempotencyKey == "" {
+		response.BadRequest(c, "缺少幂等键")
+		return
+	}
+
+	// 检查是否已处理
+	key := fmt.Sprintf("idempotency:%s:%s", tenantID, idempotencyKey)
+	exists, result, err := h.idempotency.Check(c.Request.Context(), key)
+	if err != nil {
+		response.InternalError(c, err.Error())
+		return
+	}
+	if exists {
+		response.Success(c, result) // 返回之前的结果
+		return
+	}
+
+	// 处理请求
+	entity, err := h.svc.Create(c.Request.Context(), tenantID, input)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+
+	// 保存结果
+	h.idempotency.Save(c.Request.Context(), key, entity, 24*time.Hour)
+	response.Created(c, entity)
+}
+```
+
+---
+
+## 异步任务编排
+
+### 1. 任务链模式
+
+```go
+// domain/jobs/chain.go
+package jobs
+
+type ChainJob struct {
+	steps []Step
+}
+
+type Step struct {
+	Name    string
+	Execute func(ctx context.Context, params jobs.Params, prevResult interface{}) (interface{}, error)
+}
+
+func (j *ChainJob) Execute(ctx context.Context, params jobs.Params, progress jobs.ProgressReporter) error {
+	var prevResult interface{}
+	totalSteps := len(j.steps)
+
+	for i, step := range j.steps {
+		progress.Update(
+			int(float64(i)/float64(totalSteps)*100),
+			fmt.Sprintf("执行步骤: %s", step.Name),
+		)
+
+		result, err := step.Execute(ctx, params, prevResult)
+		if err != nil {
+			return fmt.Errorf("步骤 %s 失败: %w", step.Name, err)
+		}
+		prevResult = result
+	}
+
+	progress.Update(100, "任务完成")
+	progress.SetResult(prevResult)
+	return nil
+}
+
+// 使用示例：订单导出任务链
+func NewOrderExportChain(repo *OrderRepository, storage storage.Service) *ChainJob {
+	return &ChainJob{
+		steps: []Step{
+			{
+				Name: "查询数据",
+				Execute: func(ctx context.Context, params jobs.Params, _ interface{}) (interface{}, error) {
+					tenantID := params.GetUint("tenant_id")
+					return repo.ListAll(ctx, tenantID)
+				},
+			},
+			{
+				Name: "生成 Excel",
+				Execute: func(ctx context.Context, params jobs.Params, prev interface{}) (interface{}, error) {
+					orders := prev.([]models.Order)
+					return generateExcel(orders)
+				},
+			},
+			{
+				Name: "上传文件",
+				Execute: func(ctx context.Context, params jobs.Params, prev interface{}) (interface{}, error) {
+					data := prev.([]byte)
+					return storage.Upload(ctx, "orders.xlsx", data)
+				},
+			},
+		},
+	}
+}
+```
+
+---
+
+## 前端状态管理模式
+
+### 1. 模块级状态 Store
+
+```typescript
+// stores/orderStore.ts
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+import type { Order, OrderFilter } from '../types'
+import { listOrders, getOrder, createOrder } from '../services/api'
+
+interface OrderState {
+  // 数据
+  orders: Order[]
+  currentOrder: Order | null
+  total: number
+
+  // 加载状态
+  loading: boolean
+  error: string | null
+
+  // 过滤和分页
+  filter: OrderFilter
+  page: number
+  pageSize: number
+
+  // Actions
+  fetchOrders: () => Promise<void>
+  fetchOrder: (id: number) => Promise<void>
+  createOrder: (input: CreateOrderInput) => Promise<Order>
+  setFilter: (filter: Partial<OrderFilter>) => void
+  setPage: (page: number) => void
+  reset: () => void
+}
+
+export const useOrderStore = create<OrderState>()(
+  persist(
+    (set, get) => ({
+      orders: [],
+      currentOrder: null,
+      total: 0,
+      loading: false,
+      error: null,
+      filter: {},
+      page: 1,
+      pageSize: 10,
+
+      fetchOrders: async () => {
+        const { filter, page, pageSize } = get()
+        set({ loading: true, error: null })
+
+        try {
+          const result = await listOrders({ ...filter, page, page_size: pageSize })
+          set({ orders: result.items, total: result.total })
+        } catch (err) {
+          set({ error: err instanceof Error ? err.message : '加载失败' })
+        } finally {
+          set({ loading: false })
+        }
+      },
+
+      fetchOrder: async (id: number) => {
+        set({ loading: true, error: null })
+        try {
+          const order = await getOrder(id)
+          set({ currentOrder: order })
+        } catch (err) {
+          set({ error: err instanceof Error ? err.message : '加载失败' })
+        } finally {
+          set({ loading: false })
+        }
+      },
+
+      createOrder: async (input) => {
+        set({ loading: true, error: null })
+        try {
+          const order = await createOrder(input)
+          // 刷新列表
+          get().fetchOrders()
+          return order
+        } finally {
+          set({ loading: false })
+        }
+      },
+
+      setFilter: (newFilter) => {
+        set((state) => ({
+          filter: { ...state.filter, ...newFilter },
+          page: 1, // 重置页码
+        }))
+        get().fetchOrders()
+      },
+
+      setPage: (page) => {
+        set({ page })
+        get().fetchOrders()
+      },
+
+      reset: () => {
+        set({
+          orders: [],
+          currentOrder: null,
+          total: 0,
+          filter: {},
+          page: 1,
+          error: null,
+        })
+      },
+    }),
+    {
+      name: 'order-store',
+      partialize: (state) => ({ filter: state.filter, pageSize: state.pageSize }),
+    }
+  )
+)
+```
+
+### 2. 在组件中使用
+
+```tsx
+// pages/OrderListPage.tsx
+import { useEffect } from 'react'
+import { useOrderStore } from '../stores/orderStore'
+
+export function OrderListPage() {
+  const {
+    orders,
+    total,
+    loading,
+    error,
+    page,
+    pageSize,
+    filter,
+    fetchOrders,
+    setFilter,
+    setPage
+  } = useOrderStore()
+
+  useEffect(() => {
+    fetchOrders()
+  }, [fetchOrders])
+
+  // ... 渲染逻辑
+}
+```
+
+---
+
+## 快速参考
+
+| 模式 | 使用场景 | 关键点 |
+|------|---------|--------|
+| 跨模块调用 | 模块间服务依赖 | 依赖注入 + 接口隔离 |
+| 事件驱动 | 松耦合通知 | 事件总线 + 异步处理 |
+| 状态机 | 复杂状态流转 | 转换规则 + 状态日志 |
+| 多租户 | 数据隔离 | 中间件 + 双重验证 |
+| 缓存 | 性能优化 | 读穿透 + 主动失效 |
+| 分布式锁 | 并发控制 | Redis SETNX + TTL |
+| 幂等性 | 重复请求 | 幂等键 + 结果缓存 |
+| 任务链 | 复杂异步任务 | 步骤拆分 + 进度汇报 |
+| 状态管理 | 前端复杂状态 | Zustand + 持久化 |