feat: 添加状态缓存管理 GitHub Action，支持多种操作模式（获取、设置、删除），实现缓存过期控制，优化状态管理逻辑，更新文档以反映新功能和使用示例。

cache-state/examples/feature-flags.yml

@@ -0,0 +1,326 @@
+# 功能开关状态管理示例
+# 演示如何使用状态缓存来管理功能开关、配置参数等动态配置
+
+name: Cache State - 功能开关管理
+
+on:
+  workflow_dispatch:
+    inputs:
+      feature_name:
+        description: '功能名称'
+        required: true
+        default: 'new-ui'
+      feature_enabled:
+        description: '是否启用功能'
+        required: false
+        default: true
+        type: boolean
+      rollout_percentage:
+        description: '灰度发布百分比 (0-100)'
+        required: false
+        default: '50'
+      environment:
+        description: '目标环境'
+        required: false
+        default: 'staging'
+        type: choice
+        options:
+          - development
+          - staging
+          - production
+
+jobs:
+  manage-feature-flags:
+    runs-on: ubuntu-latest
+    outputs:
+      feature-state: ${{ steps.feature-flag.outputs.state-value }}
+      rollout-config: ${{ steps.rollout.outputs.state-value }}
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 获取或设置功能开关状态
+        id: feature-flag
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'feature-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: ${{ github.event.inputs.feature_enabled }}
+          default-value: 'false'
+          cache-prefix: 'feature-flags'
+          action: 'get-or-set'
+
+      - name: 管理灰度发布配置
+        id: rollout
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'rollout-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: ${{ github.event.inputs.rollout_percentage }}
+          default-value: '0'
+          cache-prefix: 'rollout-config'
+          action: 'get-or-set'
+
+      - name: 记录功能开关变更历史
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'feature-history-${{ github.event.inputs.feature_name }}'
+          state-value: '${{ github.event.inputs.environment }}:${{ github.event.inputs.feature_enabled }}:${{ github.run_started_at }}'
+          cache-prefix: 'feature-history'
+          action: 'set'
+
+      - name: 验证功能开关配置
+        run: |
+          FEATURE_ENABLED="${{ steps.feature-flag.outputs.state-value }}"
+          ROLLOUT_PERCENT="${{ steps.rollout.outputs.state-value }}"
+          
+          echo "🎛️ 功能开关配置验证:"
+          echo "  - 功能名称: ${{ github.event.inputs.feature_name }}"
+          echo "  - 环境: ${{ github.event.inputs.environment }}"
+          echo "  - 功能状态: ${FEATURE_ENABLED}"
+          echo "  - 灰度百分比: ${ROLLOUT_PERCENT}%"
+          echo "  - 缓存命中: ${{ steps.feature-flag.outputs.cache-hit }}"
+          
+          # 验证配置合理性
+          if [[ "${FEATURE_ENABLED}" == "true" && "${ROLLOUT_PERCENT}" -gt 0 ]]; then
+            echo "✅ 功能配置有效"
+          elif [[ "${FEATURE_ENABLED}" == "false" ]]; then
+            echo "ℹ️ 功能已禁用"
+          else
+            echo "⚠️ 功能配置可能需要检查"
+          fi
+
+  apply-feature-configuration:
+    needs: manage-feature-flags
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        service: [api, frontend, mobile]
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 获取服务特定的功能配置
+        id: service-config
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'service-config-${{ matrix.service }}-${{ github.event.inputs.environment }}'
+          default-value: '{"features":{},"version":"1.0"}'
+          action: 'get'
+          cache-prefix: 'service-config'
+
+      - name: 应用功能配置到服务
+        run: |
+          SERVICE="${{ matrix.service }}"
+          FEATURE_NAME="${{ github.event.inputs.feature_name }}"
+          FEATURE_ENABLED="${{ needs.manage-feature-flags.outputs.feature-state }}"
+          ROLLOUT_PERCENT="${{ needs.manage-feature-flags.outputs.rollout-config }}"
+          
+          echo "🔧 为 ${SERVICE} 服务应用功能配置:"
+          echo "  - 功能: ${FEATURE_NAME}"
+          echo "  - 状态: ${FEATURE_ENABLED}"
+          echo "  - 灰度: ${ROLLOUT_PERCENT}%"
+          
+          # 模拟配置应用过程
+          case "${SERVICE}" in
+            "api")
+              echo "  📡 API服务配置已更新"
+              ;;
+            "frontend")
+              echo "  🌐 前端服务配置已更新"
+              ;;
+            "mobile")
+              echo "  📱 移动端配置已更新"
+              ;;
+          esac
+
+      - name: 更新服务配置状态
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'service-config-applied-${{ matrix.service }}'
+          state-value: '${{ github.event.inputs.feature_name }}:${{ needs.manage-feature-flags.outputs.feature-state }}'
+          cache-prefix: 'service-status'
+          action: 'set'
+
+  monitor-feature-metrics:
+    needs: [manage-feature-flags, apply-feature-configuration]
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 初始化功能监控指标
+        id: init-metrics
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'metrics-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          default-value: '{"users":0,"errors":0,"performance":100}'
+          action: 'get'
+          cache-prefix: 'feature-metrics'
+
+      - name: 模拟收集功能使用指标
+        run: |
+          echo "📊 收集功能使用指标..."
+          
+          # 模拟指标收集
+          USERS_COUNT=$((RANDOM % 1000 + 100))
+          ERROR_COUNT=$((RANDOM % 10))
+          PERFORMANCE_SCORE=$((RANDOM % 20 + 80))
+          
+          echo "  - 用户数: ${USERS_COUNT}"
+          echo "  - 错误数: ${ERROR_COUNT}"
+          echo "  - 性能分数: ${PERFORMANCE_SCORE}"
+          
+          # 保存到环境变量供后续步骤使用
+          echo "users_count=${USERS_COUNT}" >> $GITHUB_ENV
+          echo "error_count=${ERROR_COUNT}" >> $GITHUB_ENV
+          echo "performance_score=${PERFORMANCE_SCORE}" >> $GITHUB_ENV
+
+      - name: 更新功能监控指标
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'metrics-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: '{"users":${{ env.users_count }},"errors":${{ env.error_count }},"performance":${{ env.performance_score }}}'
+          cache-prefix: 'feature-metrics'
+          action: 'set'
+
+      - name: 分析指标异常
+        run: |
+          ERROR_COUNT=${{ env.error_count }}
+          PERFORMANCE_SCORE=${{ env.performance_score }}
+          
+          echo "🔍 指标异常分析:"
+          
+          if [[ ${ERROR_COUNT} -gt 5 ]]; then
+            echo "⚠️ 错误率偏高，可能需要回滚功能"
+            echo "alert=high_error_rate" >> $GITHUB_ENV
+          elif [[ ${PERFORMANCE_SCORE} -lt 70 ]]; then
+            echo "⚠️ 性能下降，需要关注"
+            echo "alert=performance_degradation" >> $GITHUB_ENV
+          else
+            echo "✅ 指标正常"
+            echo "alert=none" >> $GITHUB_ENV
+          fi
+
+      - name: 记录异常告警
+        if: env.alert != 'none'
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'alert-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: '${{ env.alert }}:${{ github.run_started_at }}'
+          cache-prefix: 'alerts'
+          action: 'set'
+
+  feature-rollback-if-needed:
+    needs: [manage-feature-flags, monitor-feature-metrics]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 检查是否需要回滚
+        id: check-rollback
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'alert-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          default-value: 'none'
+          action: 'get'
+          cache-prefix: 'alerts'
+
+      - name: 执行自动回滚
+        if: contains(steps.check-rollback.outputs.state-value, 'high_error_rate')
+        run: |
+          echo "🔄 检测到高错误率，执行自动回滚..."
+          echo "功能: ${{ github.event.inputs.feature_name }}"
+          echo "环境: ${{ github.event.inputs.environment }}"
+
+      - name: 禁用功能开关
+        if: contains(steps.check-rollback.outputs.state-value, 'high_error_rate')
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'feature-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: 'false'
+          cache-prefix: 'feature-flags'
+          action: 'set'
+
+      - name: 记录回滚操作
+        if: contains(steps.check-rollback.outputs.state-value, 'high_error_rate')
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'rollback-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: 'auto-rollback:${{ github.run_started_at }}'
+          cache-prefix: 'rollback-history'
+          action: 'set'
+
+  generate-feature-report:
+    needs: [manage-feature-flags, apply-feature-configuration, monitor-feature-metrics, feature-rollback-if-needed]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 收集所有功能状态
+        run: |
+          echo "📋 功能开关管理报告"
+          echo "===================="
+          echo "时间: $(date)"
+          echo "功能: ${{ github.event.inputs.feature_name }}"
+          echo "环境: ${{ github.event.inputs.environment }}"
+          echo ""
+
+      - name: 获取最终功能状态
+        id: final-state
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'feature-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          action: 'get'
+          cache-prefix: 'feature-flags'
+
+      - name: 获取监控指标
+        id: final-metrics
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'metrics-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          action: 'get'
+          cache-prefix: 'feature-metrics'
+
+      - name: 检查回滚历史
+        id: rollback-check
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'rollback-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          default-value: 'none'
+          action: 'get'
+          cache-prefix: 'rollback-history'
+
+      - name: 生成最终报告
+        run: |
+          echo "✅ 功能状态管理完成"
+          echo ""
+          echo "📊 最终状态:"
+          echo "  - 功能状态: ${{ steps.final-state.outputs.state-value }}"
+          echo "  - 监控指标: ${{ steps.final-metrics.outputs.state-value }}"
+          echo "  - 回滚历史: ${{ steps.rollback-check.outputs.state-value }}"
+          echo ""
+          echo "🎯 下次运行时，这些状态将被保留并可以继续使用。"
+
+  cleanup-old-feature-states:
+    runs-on: ubuntu-latest
+    if: github.event.inputs.environment == 'development'  # 只在开发环境清理
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 清理过期的功能状态
+        run: |
+          echo "🧹 清理开发环境的过期功能状态..."
+          # 这里可以实现清理逻辑
+          # 例如，清理超过一定时间的开发环境功能开关
+
+      - name: 重置开发环境告警
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'dev-alerts-cleared'
+          state-value: '${{ github.run_started_at }}'
+          cache-prefix: 'cleanup'
+          action: 'set'