@colin4k1024/tsp 2.4.0

package/skills/git-worktree-isolation/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: git-worktree-isolation
+description: >
+  基于 Git Worktree 的任务隔离工作流：每个开发任务在独立 worktree 中执行，
+  确保主工作区干净、并行任务互不干扰，完成后结构化决策合并/PR/保留/丢弃。
+  与 parallel-execution 的 worktree 基础设施互补，本 skill 聚焦任务级隔离策略。
+origin: superpowers-using-git-worktrees + harness-engineering
+---
+
+# Git Worktree Isolation
+
+## 用途
+
+- 确保每个开发任务（feature / fix / spike）在 **隔离的 worktree + 分支** 中执行，主工作区始终保持可切换状态。
+- 在多 agent 并行场景下，每个 agent 拥有独立文件系统视图，避免写冲突。
+- 任务完成后提供 **结构化收口决策**（merge / PR / keep / discard），而不是任凭 worktree 积累。
+
+## 触发信号
+
+- `/team-execute` 分派的并行实现任务。
+- `wave-execution` 中同一 Wave 的多个工作项。
+- 需要在不影响主分支的情况下进行探索性实现或 spike。
+- 当前工作区有未提交变更，但需要紧急处理另一个任务。
+- Code review 后的修改需要在隔离环境中完成。
+
+## 核心原则
+
+1. **一个任务 = 一个 worktree = 一个分支**——不共用 worktree。
+2. **worktree 有明确生命周期**——创建时绑定任务 ID，完成后必须做收口决策。
+3. **主工作区是调度中心**——编排和合并在主工作区进行，实现在 worktree 中进行。
+
+## 工作流
+
+### 1. 创建隔离环境
+
+```bash
+# 命名规则: .worktrees/{slug}-{task-id}
+git worktree add .worktrees/{slug}-{task-id} -b task/{slug}/{task-id}
+
+# 验证隔离
+cd .worktrees/{slug}-{task-id}
+git branch --show-current   # → task/{slug}/{task-id}
+```
+
+**命名约定：**
+
+| 元素 | 格式 | 示例 |
+|------|------|------|
+| Worktree 路径 | `.worktrees/{slug}-{task-id}` | `.worktrees/auth-T001` |
+| 分支名 | `task/{slug}/{task-id}` | `task/auth/T001` |
+| Spike 分支 | `spike/{slug}/{description}` | `spike/auth/oauth-flow` |
+
+### 2. 在 worktree 中执行
+
+```
+进入 worktree 目录 →
+  加载任务上下文（STATE.md 对应工作项）→
+  执行实现 →
+  运行测试 →
+  提交到 worktree 分支
+```
+
+**执行约束：**
+
+- 每个 worktree 中的 agent 只操作任务范围内的文件。
+- 不在 worktree 中修改共享配置（package.json / pom.xml 等），除非任务明确要求。
+- 提交信息包含任务 ID：`feat(T001): implement auth flow`。
+
+### 3. 收口决策
+
+任务完成后，在 **主工作区** 执行收口：
+
+| 决策 | 条件 | 操作 |
+|------|------|------|
+| **Merge** | 代码通过 review + 测试 | `git merge task/{slug}/{task-id}` + 清理 worktree |
+| **PR** | 需要异步 review 或 CI | 创建 PR + 保留 worktree 直到合并 |
+| **Keep** | 任务暂停但稳定 | 标记为 `paused`，保留 worktree |
+| **Discard** | spike 完成或方向废弃 | 删除 worktree + 分支 |
+
+```bash
+# Merge 路径
+cd /path/to/main-worktree
+git merge --no-ff task/{slug}/{task-id} -m "feat(T001): implement auth flow"
+git worktree remove .worktrees/{slug}-{task-id}
+git branch -d task/{slug}/{task-id}
+
+# Discard 路径
+git worktree remove --force .worktrees/{slug}-{task-id}
+git branch -D spike/{slug}/{description}
+```
+
+### 4. 清理巡检
+
+定期（或每次 `/team-review` 前）执行清理：
+
+```bash
+# 列出所有 worktree
+git worktree list
+
+# 清理已删除的 worktree 引用
+git worktree prune
+
+# 查找已合并但未清理的任务分支
+git branch --merged main | grep 'task/'
+```
+
+## 与 parallel-execution 的关系
+
+| 关注点 | parallel-execution | git-worktree-isolation |
+|--------|-------------------|----------------------|
+| 核心目标 | 多实例并行加速 | 任务级文件隔离 |
+| Worktree 使用 | 作为并行基础设施 | 作为隔离策略 |
+| 分支管理 | 自动创建/合并 | 结构化收口决策 |
+| 清理策略 | 任务结束自动清理 | 显式四选一决策 |
+| 集成点 | wave-execution 调用 | 为 parallel-execution 提供隔离规范 |
+
+`parallel-execution` 调用 `git-worktree-isolation` 的隔离规范创建 worktree，`git-worktree-isolation` 依赖 `parallel-execution` 的任务分发能力。
+
+## 与 session-continuity 的关系
+
+- `/pause` 时：记录活跃 worktree 列表到 HANDOFF.json 的 `active_worktrees` 字段。
+- `/resume` 时：检查 worktree 状态，标记哪些仍然有效、哪些需要清理。
+
+## 配套约束
+
+1. `.worktrees/` 目录加入 `.gitignore`，不提交到远程仓库。
+2. worktree 中不执行 `git rebase` 主分支——避免在隔离环境中引入合并复杂度。
+3. 超过 7 天未活动的 worktree 在清理巡检时标记为候选清理项。
+4. 共享锁文件（lockfile）变更在 merge 阶段统一解决，不在 worktree 中各自更新。
+
+## 验证标准
+
+- [ ] 创建的 worktree 路径遵循 `.worktrees/{slug}-{task-id}` 命名规范
+- [ ] 每个 worktree 对应唯一分支，无分支共用
+- [ ] 任务完成后在 24h 内执行收口决策（merge / PR / keep / discard）
+- [ ] `git worktree list` 无孤立 worktree
+- [ ] 已合并分支已被删除

package/skills/goframe-v2/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: goframe-v2
+description: GoFrame development skill. TRIGGER when writing/modifying Go files, implementing services, creating APIs, or database operations. DO NOT TRIGGER for frontend/shell scripts.
+license: Apache-2.0
+---
+
+# Critical Conventions
+
+## Project Development Standards
+- For complete projects (HTTP/microservices), install GoFrame CLI and use `gf init` to create project scaffolding. See [Project Creation - init](./references/开发工具/项目创建-init.md) for details.
+- Auto-generated code files (dao, do, entity) MUST NOT be manually created or modified per GoFrame conventions.
+- Unless explicitly requested, do NOT use the `logic/` directory for business logic. Implement business logic directly in the `service/` directory.
+- Reference complete project examples:
+  - HTTP service best practice: [user-http-service](./examples/practices/user-http-service)
+  - gRPC service best practice: [user-grpc-service](./examples/practices/user-grpc-service)
+
+## Component Usage Standards
+- Before creating new methods or variables, check if they already exist elsewhere and reuse existing implementations.
+- Use the `gerror` component for all error handling to ensure complete stack traces for traceability.
+- When exploring new components, prioritize GoFrame built-in components and reference best practice code from examples.
+- **Database Operations MUST use DO objects** (`internal/model/do/`), never `g.Map` or `map[string]interface{}`. DO struct fields are `interface{}`; unset fields remain `nil` and are automatically ignored by the ORM:
+  ```go
+  // Good - use DO object
+  dao.Users.Ctx(ctx).Where(cols.Id, id).Data(do.User{Uid: uid}).Update()
+
+  // Good - conditional fields, unset fields are nil and ignored
+  data := do.User{}
+  if password != "" { data.PasswordHash = hash }
+  if isAdmin != nil { data.IsAdmin = *isAdmin }
+  dao.Users.Ctx(ctx).Where(cols.Id, id).Data(data).Update()
+
+  // Good - explicitly set a column to NULL using gdb.Raw
+  dao.Instances.Ctx(ctx).Where(cols.Id, id).Data(do.Instance{IdleSince: gdb.Raw("NULL")}).Update()
+
+  // Bad - never use g.Map for database operations
+  dao.Users.Ctx(ctx).Data(g.Map{cols.Uid: uid}).Update()
+  ```
+## Code Style Standards
+- **Variable Declarations**: When defining multiple variables, use a `var` block to group them for better alignment and readability:
+  ```go
+  // Good - aligned and clean
+  var (
+      authSvc       *auth.Service
+      bizCtxSvc     *bizctx.Service
+      k8sSvc        *svcK8s.Service
+      notebookSvc   *notebook.Service
+      middlewareSvc *middleware.Service
+  )
+
+  // Avoid - scattered declarations
+  authSvc := auth.New()
+  bizCtxSvc := bizctx.New()
+  k8sSvc := svcK8s.New()
+  ```
+- Apply this pattern when you have 3 or more related variable declarations in the same scope.
+
+## Soft Delete & Time Maintenance
+
+GoFrame provides **automatic** soft delete and time maintenance features. When a table contains `created_at`, `updated_at`, or `deleted_at` fields, the ORM handles these automatically.
+
+### Automatic Time Fields
+
+| Field | Auto Behavior |
+|-------|---------------|
+| `created_at` | Auto-written on `Insert/InsertAndGetId`, never modified afterward |
+| `updated_at` | Auto-written on `Insert/Update/Save` |
+| `deleted_at` | Auto-written on `Delete` (soft delete), auto-filtered on queries |
+
+### Critical Rules
+
+**1. NEVER manually set time fields** - GoFrame handles these automatically:
+```go
+// WRONG - redundant manual time setting
+dao.User.Ctx(ctx).Data(do.User{
+    Name:      "john",
+    CreatedAt: gtime.Now(),  // REDUNDANT! Framework handles this
+    UpdatedAt: gtime.Now(),  // REDUNDANT! Framework handles this
+}).Insert()
+
+// CORRECT - let framework handle time fields
+dao.User.Ctx(ctx).Data(do.User{
+    Name: "john",
+}).Insert()
+```
+
+**2. NEVER manually add `WhereNull(cols.DeletedAt)`** - GoFrame auto-adds soft delete filter:
+```go
+// WRONG - redundant soft delete condition
+dao.User.Ctx(ctx).
+    Where(do.User{Status: 1}).
+    WhereNull(cols.DeletedAt).  // REDUNDANT! Framework auto-adds this
+    Scan(&list)
+
+// CORRECT - framework auto-adds deleted_at IS NULL
+dao.User.Ctx(ctx).
+    Where(do.User{Status: 1}).
+    Scan(&list)
+```
+
+**3. Use `Delete()` for soft delete** - Framework converts to `UPDATE SET deleted_at = NOW()`:
+```go
+// CORRECT - use Delete(), framework handles soft delete
+dao.User.Ctx(ctx).Where(do.User{Id: id}).Delete()
+// Actual SQL: UPDATE `sys_user` SET `deleted_at`=NOW() WHERE `id`=?
+
+// WRONG - manual Update with deleted_at
+dao.User.Ctx(ctx).
+    Where(do.User{Id: id}).
+    Data(do.User{DeletedAt: gtime.Now()}).  // REDUNDANT!
+    Update()
+```
+
+### Field Type Support
+
+The `deleted_at` field supports multiple types:
+- **DateTime/Timestamp**: Default, stores deletion time
+- **Integer**: Stores Unix timestamp (seconds)
+- **Boolean**: Stores 0/1 for deleted state
+
+### Configuration (Optional)
+
+Time field names can be customized in `config.yaml`:
+```yaml
+database:
+  default:
+    createdAt: "created_at"   # Custom field name
+    updatedAt: "updated_at"
+    deletedAt: "deleted_at"
+    timeMaintainDisabled: false  # Set true to disable this feature
+```
+
+# GoFrame Documentation
+Complete GoFrame development resources covering component design, usage, best practices, and considerations: [GoFrame Documentation](./references/README.MD)
+
+# GoFrame Code Examples
+Rich practical code examples covering HTTP services, gRPC services, and various project types: [GoFrame Examples](./examples/README.MD)

package/skills/goframe-v2/examples/README.MD

@@ -0,0 +1,53 @@
+| 示例代码 | 示例介绍 |
+| --- | --- |
+| [balancer/http](balancer/http) | 演示如何使用GoFrame框架结合etcd实现HTTP服务的负载均衡功能。本示例展示了基于客户端的负载均衡实现，采用轮询策略进行请求分发，支持自动服务发现和动态路由。主要功能包括：使用etcd进行服务注册与发现、客户端轮询负载均衡策略、多服务实例请求分发、与GoFrame的HTTP服务器和客户端组件无缝集成，适用于构建高可用、可扩展的微服务架构系统。通过本示例可以学习如何在分布式环境中实现服务负载均衡和服务发现机制。 |
+| [balancer/polaris](balancer/polaris) | 演示如何使用GoFrame框架集成Polaris服务网格平台实现HTTP服务的负载均衡功能。本示例展示了基于Polaris的服务注册与发现机制、客户端轮询负载均衡策略、本地缓存配置优化性能、以及集中式日志管理。主要功能包括:使用Polaris作为服务注册中心、可配置的TTL(存活时间)心跳机制、自动服务发现、动态请求路由、与GoFrame的HTTP服务器和客户端组件无缝集成,适用于构建云原生微服务架构并提供高级流量管理能力。通过本示例可以学习如何在分布式环境中使用Polaris实现服务治理、负载均衡和故障转移等企业级特性。 |
+| [config/apollo](config/apollo) | 演示如何在GoFrame应用程序中无缝集成Apollo配置中心实现集中式配置管理。本示例展示了Apollo客户端的初始化与配置、配置适配器的实现方法、动态配置加载与解析、实时配置更新机制、完善的错误处理和日志记录、以及配置值的获取方式。主要功能包括:通过Apollo实现集中式配置管理、支持多环境和命名空间、自动配置刷新能力、使用GoFrame配置组件进行类型安全的配置访问、生产级错误处理机制。适用于构建需要集中配置管理、无需重启即可动态更新配置、支持配置版本管理和回滚的微服务应用。通过本示例可以学习配置中心在分布式系统中的最佳实践。 |
+| [config/consul](config/consul) | 演示如何在GoFrame应用程序中全面集成HashiCorp Consul配置中心实现分布式配置管理。本示例展示了Consul客户端的设置与初始化、GoFrame配置组件的适配器实现、动态配置加载与解析、实时配置监听与更新、完善的错误处理和日志记录、以及安全的配置值获取。主要功能包括:通过Consul KV存储实现分布式配置管理、支持多数据中心和命名空间、自动配置同步、健康检查与服务发现集成、类型安全的配置访问、生产级错误处理机制。非常适合构建需要分布式配置管理、服务网格集成、多实例间配置一致性的云原生微服务应用。通过本示例可以学习如何使用Consul实现企业级分布式配置管理和服务治理。 |
+| [config/kubecm](config/kubecm) | 演示如何在GoFrame应用程序中全面集成Kubernetes ConfigMap实现云原生配置管理。本示例展示了Pod内部和外部两种配置场景、Kubernetes客户端的初始化与认证、ConfigMap的访问与动态加载、实时配置监听与更新、命名空间和资源管理、完善的错误处理和日志记录、以及安全的配置值获取。主要功能包括:原生Kubernetes ConfigMap集成、支持多种部署场景(集群内和集群外)、ConfigMap变更时自动刷新配置、与GoFrame配置组件无缝集成、符合RBAC规范的访问模式、生产级错误处理机制。非常适合构建部署在Kubernetes上的云原生应用,特别是需要原生配置管理、GitOps工作流、配置即代码实践的场景。通过本示例可以学习如何在Kubernetes环境中实现声明式配置管理和云原生最佳实践。 |
+| [config/nacos](config/nacos) | 演示如何在GoFrame应用程序中无缝集成阿里巴巴Nacos配置中心实现动态配置管理。本示例展示了Nacos客户端的初始化与配置、GoFrame配置组件适配器的实现、动态配置加载与热更新、实时配置监听与变更通知、命名空间和分组管理、完善的错误处理和日志记录、以及安全的配置值获取。主要功能包括:通过Nacos实现集中式配置管理、支持多环境和命名空间隔离、无需重启服务即可自动刷新配置、配置版本管理与回滚能力、类型安全的配置访问、生产级监控能力。非常适合构建阿里云或本地部署的云原生微服务应用,特别是需要动态配置、服务发现、分布式系统间配置共享的场景。通过本示例可以深入学习Nacos在配置管理和服务治理方面的企业级应用实践。 |
+| [config/polaris](config/polaris) | 演示如何在GoFrame应用程序中无缝集成腾讯云Polaris配置中心实现服务网格配置管理。本示例展示了Polaris客户端的设置与初始化、GoFrame配置组件适配器的实现、动态配置加载与热更新、实时配置监听与同步、命名空间和文件分组管理、完善的错误处理和日志记录、以及安全的配置值获取。主要功能包括:通过Polaris实现集中式配置管理、支持多命名空间和配置分组、自动配置刷新能力、与Polaris服务网格集成实现统一服务治理、类型安全的配置访问、生产级监控能力。非常适合构建基于腾讯云或使用Polaris网格的云原生微服务应用,特别是需要动态配置、服务发现、流量管理、统一配置治理的场景。通过本示例可以深入学习Polaris在配置管理和服务网格方面的企业级应用实践。 |
+| [database/encoded-pass](database/encoded-pass) | 演示如何在GoFrame中实现自定义数据库驱动以处理加密的数据库密码，提升应用程序安全性。本示例展示了如何创建带有AES加密和Base64编码的自定义MySQL驱动、连接建立时的自动密码解密机制、配置文件中的安全凭据存储、透明的数据库连接处理、以及与GoFrame数据库组件的无缝集成。主要功能包括:加密密码存储、自定义驱动注册、自动解密中间件、生产级安全模式、对现有数据库操作零影响。非常适合需要增强数据库安全性、符合安全策略合规要求、保护版本控制中的敏感凭据、无需代码更改即可实现安全配置管理的应用程序。通过本示例可以学习如何在不影响开发效率的前提下提升数据库连接的安全性，以及如何实现自定义数据库驱动扩展GoFrame的能力。 |
+| [grpc/balancer](grpc/balancer) | 演示在GoFrame中实现全面的gRPC负载均衡以构建弹性分布式系统。本示例展示了如何使用多种策略配置gRPC负载均衡器、实现客户端负载均衡以获得最佳性能、与etcd等服务发现机制集成、处理自动故障转移和服务健康检查、在多个服务器实例间分发请求、以及管理连接池。主要功能包括:多种负载均衡算法(轮询、加权、最少连接)、自动服务实例发现、基于健康状态的路由、连接状态管理、重试策略、生产级错误处理。非常适合构建高可用微服务、实现容错分布式系统、水平扩展gRPC服务、确保跨服务实例的最佳资源利用。通过本示例可以学习如何在分布式环境中实现gRPC负载均衡、服务发现与负载均衡的协同工作、以及构建高可用高性能微服务架构的最佳实践。 |
+| [grpc/basic](grpc/basic) | 演示GoFrame应用程序中gRPC的基础实现，涵盖协议缓冲区定义、服务创建和客户端-服务器通信。本示例展示了如何使用GoFrame创建gRPC服务器和客户端、定义和编译用于服务契约的协议缓冲区、实现带有业务逻辑的服务处理器、进行同步和异步RPC调用、处理错误和状态码、以及与GoFrame的配置和日志系统集成。主要功能包括:完整的服务器和客户端设置、协议缓冲区集成、服务接口实现、请求-响应模式、错误处理最佳实践、生产级代码结构。非常适合gRPC新手开发者、使用GoFrame构建微服务、学习协议缓冲区使用、实现服务间通信模式的场景。通过本示例可以学习gRPC在GoFrame中的基础用法、微服务通信的最佳实践、以及如何构建高效的RPC服务。 |
+| [grpc/ctx](grpc/ctx) | 演示在GoFrame的gRPC服务中进行高级上下文和元数据管理，用于请求跟踪和数据传播。本示例展示了如何通过gRPC上下文传递元数据以处理横切关注点、处理上下文值和截止时间以实现请求取消、跨服务边界管理请求上下文、处理和提取上下文元数据、实现分布式追踪集成、以及传播认证令牌和关联ID。主要功能包括:元数据注入和提取、上下文超时和取消处理、自定义元数据键和值、基于拦截器的元数据处理、分布式追踪支持、请求关联模式。非常适合在微服务中实现可观测性、跨分布式系统追踪请求、实现认证和授权、管理请求超时和取消、构建具有适当上下文管理的生产级gRPC服务。通过本示例可以学习gRPC上下文的高级用法、如何在分布式系统中传播请求信息、以及实现微服务间通信的最佳实践和可观测性模式。 |
+| [grpc/rawgrpc](grpc/rawgrpc) | 演示在GoFrame中不使用框架抽象层直接实现原生gRPC，提供最大的控制力和灵活性。本示例展示了如何直接使用原生gRPC库创建gRPC服务器和客户端、不使用额外封装直接使用协议缓冲区、通过直接gRPC API访问实现服务处理器、进行具有完全控制权的低级RPC调用、处理流式RPC和高级模式、以及有选择地集成GoFrame组件。主要功能包括:直接创建gRPC服务器和客户端、无抽象的协议缓冲区使用、手动连接管理、自定义拦截器和中间件、流式支持(单向、客户端流、服务器流、双向流)、生产级错误处理。非常适合需要细粒度控制的高级用户、实现自定义gRPC模式、优化性能关键应用、以及集成第三方gRPC库。通过本示例可以学习如何在GoFrame中使用原生gRPC、深入理解gRPC工作原理、以及实现高度定制化的RPC通信方案。 |
+| [grpc/resolver](grpc/resolver) | 演示在GoFrame中实现gRPC服务解析器并集成etcd以实现动态服务发现和解析。本示例展示了如何使用etcd作为服务注册中心配置服务解析器、通过自动心跳向etcd注册gRPC服务、使用解析器API动态发现和解析服务、自动处理服务实例的更新和移除、实现客户端服务发现、以及管理服务健康监控。主要功能包括:基于etcd的服务注册中心、自动服务注册和注销、动态服务解析、健康检查集成、服务变更时的自动故障转移、生产级连接管理。非常适合构建具有动态服务发现的云原生微服务、实现服务网格模式、无需客户端重新配置即可扩展服务、通过自动服务解析确保高可用性。通过本示例可以学习如何在gRPC中实现服务发现和解析、etcd在微服务架构中的应用、以及构建动态可扩展的分布式系统的最佳实践。 |
+| [httpserver/basic-auth](httpserver/basic-auth) | 演示在GoFrame中实现HTTP基础认证，用于简单的凭据基础访问控制。本示例展示了基础认证中间件的设置和配置、针对配置凭据的用户名和密码验证、Base64凭据编码和解码、用于浏览器提示的WWW-Authenticate头处理、受保护路由实现、自定义认证失败响应、以及与GoFrame中间件系统的集成。主要功能包括:无需外部依赖的简单认证、浏览器兼容的认证对话框、凭据验证模式、安全凭据存储建议、自定义领域配置、生产级错误处理。非常适合内部工具和管理面板、简单API保护、开发和测试环境、遗留系统集成、以及需要轻量级认证且无需复杂基础设施的应用程序。通过本示例可以学习HTTP基础认证的实现方法、如何在GoFrame中实现简单认证保护、以及基础认证的适用场景和注意事项。 |
+| [httpserver/jwt](httpserver/jwt) | 演示在GoFrame HTTP服务器中实现全面的JWT(JSON Web Token)认证，用于安全的API访问控制。本示例展示了带有自定义声明和过期时间的JWT令牌生成、令牌验证和校验中间件、使用HS256/RS256算法进行安全令牌签名、用于延长会话的刷新令牌机制、带有认证中间件的受保护路由实现、对无效或过期令牌的错误处理、以及与GoFrame中间件系统的集成。主要功能包括:用户登录和令牌颁发、无状态认证、令牌刷新模式、基于角色的访问控制(RBAC)集成、安全令牌存储建议、生产级安全实践。非常适合构建带有认证的REST API、实现微服务安全、需要无状态认证的移动应用后端、以及需要可扩展认证且无需服务器端会话的应用程序。通过本示例可以学习JWT认证的最佳实践、如何实现安全的无状态认证、以及构建安全可扩展的Web服务。 |
+| [httpserver/mcp-http](httpserver/mcp-http) | 演示使用GoFrame和HTTP流式传输实现模型上下文协议(MCP)服务器用于AI模型集成。本示例展示了使用HTTP传输的MCP服务器设置、实时模型输出的流式响应处理、协议消息编码和解码、上下文管理和传播、与AI模型和服务集成、以及MCP操作的错误处理。主要功能包括:基于HTTP的MCP传输、流式API支持、高效消息序列化、请求间上下文共享、可扩展协议处理器、生产级模式。非常适合构建AI代理后端、集成语言模型与应用、实现流式AI响应、以及创建符合MCP协议的模型上下文共享服务。通过本示例可以学习MCP协议的实现、AI模型集成最佳实践、以及构建智能AI应用。 |
+| [httpserver/mcp-sse](httpserver/mcp-sse) | 演示使用GoFrame和服务器发送事件(SSE)实现模型上下文协议(MCP)服务器用于实时AI模型通信。本示例展示了使用SSE传输的MCP服务器设置实现服务器到客户端流式传输、模型输出的实时事件流、持久连接以实现连续通信、事件格式化和客户端重连处理、与AI模型和代理集成、以及高效资源管理。主要功能包括:基于SSE的MCP传输、从服务器到客户端的单向流式传输、自动重连支持、事件驱动架构、相比WebSocket更轻量级、生产级模式。非常适合构建实时AI代理界面、实现无需WebSocket复杂性的流式模型响应、创建聊天和助手应用、以及实现模型更新的服务器推送通知。通过本示例可以学习SSE在AI应用中的使用、MCP协议实现、以及构建实时智能应用。 |
+| [httpserver/proxy](httpserver/proxy) | 演示使用GoFrame实现反向代理服务器以进行请求转发和负载分发。本示例展示了带有目标后端服务器的反向代理设置和配置、带有头保留的HTTP请求和响应转发、自定义头操作和转换、连接池和keepalive管理、错误处理和故障转移逻辑、以及与GoFrame中间件系统集成。主要功能包括:灵活的代理配置、透明请求转发、响应流支持、自定义路由规则、负载均衡集成、生产级模式。适合构建API网关和服务代理、实现微服务路由、添加认证和限流层、实现A/B测试和金丝雀部署、以及创建开发代理服务器。 |
+| [httpserver/rate-limit](httpserver/rate-limit) | 演示在GoFrame HTTP服务器中实现限流功能用于API保护和流量控制。本示例展示了带有可配置限制的限流中间件配置、令牌桶和滑动窗口算法、按IP和按用户的限流策略、自定义限流响应和头(X-RateLimit-*)、用于可扩展性的基于Redis的分布式限流、以及与GoFrame中间件链集成。主要功能包括:灵活的限流策略、分布式限流支持、每个端点的自定义限制规则、优雅的限流响应、监控和指标集成、生产级模式。非常适合保护API免受滥用和DDoS攻击、实现公平使用策略、确保负载下的服务稳定性、管理API配额和计费、以及启用多层服务级别。通过本示例可以学习限流算法、如何实现高效的流量控制、以及构建安全可靠的API服务。 |
+| [httpserver/response-json-array](httpserver/response-json-array) | 演示在GoFrame HTTP服务器中处理JSON数组响应用于RESTful API开发。本示例展示了返回JSON数组作为HTTP响应、适当的content-type头配置、带有自定义格式的数组序列化、大型数据集的分页支持、大型数组的高效内存管理、以及与GoFrame响应写入系统集成。主要功能包括:自动JSON序列化、适当的HTTP状态码、空数组处理、大型数据集的流式支持、错误响应格式化、RESTful API模式。非常适合构廻返回集合的REST API、实现列表和搜索端点、处理批量数据响应、确保一致的API响应格式、以及优化JSON序列化性能。通过本示例可以学习JSON数组响应的最佳实践、RESTful API设计、以及高效数据序列化。 |
+| [httpserver/sse](httpserver/sse) | 演示使用GoFrame实现服务器发送事件(SSE)用于实时服务器到客户端流式传输。本示例展示了带有持久连接的SSE服务器设置、带有数据、事件类型和ID的事件流格式化、带有Last-Event-ID的自动客户端重连处理、发送实时更新和通知、适当的content-type和头配置、以及连接生命周期管理。主要功能包括:从服务器到客户端的单向流式传输、自动重连支持、事件驱动架构、相比WebSocket更轻量级、心跳和keepalive支持、生产级模式。非常适合构建实时通知和更新、实现实时仪表盘和监控、创建聊天和消息功能、无需WebSocket实现服务器推送、以及构建事件驱动应用。通过本示例可以学习SSE的实现原理、与WebSocket的区别、以及构建实时通信应用。 |
+| [httpserver/swagger-auth](httpserver/swagger-auth) | 演示使用GoFrame实现带有基础认证集成的Swagger API文档用于安全的API文档访问。本示例展示了Swagger UI与GoFrame HTTP服务器集成、Swagger端点的基础认证保护、OpenAPI规范生成和服务、文档访问的认证中间件、自定义Swagger UI配置、以及与GoFrame路由系统集成。主要功能包括:受保护的API文档、自动OpenAPI规范生成、带认证的交互式API测试、可自定义的Swagger UI主题、基于凭据的访问控制、开发友好的模式。非常适合保护生产环境中的API文档、提供内部API的认证访问、实现带认证的交互式API测试、记录和保护REST API、以及维护带访问控制的API规范。通过本示例可以学习如何保护Swagger文档、集成OpenAPI规范、以及构建安全的API文档系统。 |
+| [httpserver/upload-file](httpserver/upload-file) | 演示在GoFrame HTTP服务器中处理文件上传用于多部分表单数据处理。本示例展示了单文件和多文件上传支持、多部分表单数据解析和处理、文件大小验证和限制、带有MIME类型检查的文件类型验证、带有唯一命名的安全文件存储、以及与GoFrame请求处理集成。主要功能包括:自动文件解析、可配置的上传限制、文件元数据提取、进度跟踪支持、无效上传的错误处理、生产级模式。非常适合构建文件上传API和表单、实现图像和文档上传功能、处理批量文件上传、确保安全的文件处理、以及创建内容管理系统。通过本示例可以学习文件上传的最佳实践、安全文件处理、以及构建安全可靠的文件上传功能。 |
+| [nosql/mongodb](nosql/mongodb) | 演示在GoFrame中全面集成MongoDB用于基于文档的数据存储和检索。本示例展示了使用官方Go驱动的MongoDB连接设置和配置、文档的CRUD操作(创建、读取、更新、删除)、带有过滤器和投影的高级查询、用于数据分析的聚合管道使用、用于性能优化的索引创建和管理、用于数据一致性的事务支持、以及连接池配置。主要功能包括:自动连接管理、错误处理模式、在适用情况下与GoFrame的ORM概念集成、文档序列化/反序列化、分页支持、生产级数据库操作。非常适合构建需要灵活模式设计、面向文档的数据模型、复杂聚合、水平扩展性、以及在微服务架构中集成NoSQL数据库的应用程序。通过本示例可以学习如何在GoFrame中使用MongoDB、NoSQL数据库的最佳实践、以及构建灵活高性能的文档存储系统。 |
+| [nosql/redis](nosql/redis) | 演示在GoFrame中全面集成Redis用于缓存、会话存储和数据持久化。本示例展示了使用GoFrame的redis组件进行Redis连接设置和配置、基本操作包括GET/SET/DEL、数据结构操作(字符串、哈希、列表、集合、有序集合)、TTL和过期管理、管道和事务支持、发布/订阅消息模式、以及连接池配置。主要功能包括:支持单机和集群模式、自动连接管理、错误处理和重试逻辑、与GoFrame缓存组件集成、序列化和反序列化助手、生产级模式。非常适合实现应用缓存、会话管理、限流、分布式锁、实时消息、以及在微服务架构中实现高性能数据存储。通过本示例可以学习如何在GoFrame中使用Redis、Redis数据结构的最佳实践、以及构建高性能缓存系统。 |
+| [observability/metric/basic](observability/metric/basic) | 演示在GoFrame中使用OpenTelemetry和Prometheus集成的全面基础指标类型及其用法。本示例展示了用于跟踪事件发生的计数器指标、用于测量分布的直方图指标、用于当前值的仪表指标、以及用于双向计数的UpDownCounter。主要功能包括:指标创建和注册、属性配置和标签、指标值记录和观察、与Prometheus导出器集成、OpenTelemetry指标管道设置、生产级埋点模式。非常适合学习基本指标类型、实现应用可观测性、监控服务性能、构建自定义指标仪表板、以及为GoFrame应用建立基准监控。通过本示例可以学习指标的基础概念、OpenTelemetry指标API、以及如何构建完整的监控系统。 |
+| [observability/metric/callback](observability/metric/callback) | 演示在GoFrame中使用OpenTelemetry和Prometheus实现基于回调的指标收集以进行异步指标更新。本示例展示了指标的回调函数注册、通过回调自动更新指标值、异步指标观察、可观察的计数器和仪表模式、系统资源指标收集、以及定时指标更新。主要功能包括:非阻塞指标收集、周期性回调执行、系统指标集成(CPU、内存、goroutines)、延迟指标评估、自动值刷新、生产级模式。非常适合收集系统指标、监控资源使用、实现异步指标更新、减少指标收集开销、观察计算成本高的值、以及构建对性能影响最小的高效监控系统。通过本示例可以学习异步指标收集、回调模式、以及高效的系统监控实现。 |
+| [observability/metric/dynamic_attributes](observability/metric/dynamic_attributes) | 演示在GoFrame中使用OpenTelemetry和Prometheus管理动态指标属性以实现运行时属性更新。本示例展示了运行时属性修改、基于上下文的属性注入、请求作用域的指标标签、动态属性值解析、每请求指标自定义、以及灵活的标签模式。主要功能包括:在指标记录时更新属性、从请求上下文提取属性、注入用户/租户/会话ID、动态标签值计算、属性值缓存、生产级模式。非常适合实现每请求指标标签、跟踪用户特定指标、支持多租户、使用运行时上下文丰富指标、按动态维度分析行为、以及构建适应应用状态的灵活监控系统。通过本示例可以学习动态属性管理、上下文注入、以及灵活的指标标签实践。 |
+| [observability/metric/global_attributes](observability/metric/global_attributes) | 演示在GoFrame中使用OpenTelemetry和Prometheus管理全局指标属性以实现一致的指标标签。本示例展示了全局属性配置和管理、跨所有指标自动应用属性、服务级元数据(service.name、service.version)、环境识别属性、一致的指标标签、以及属性继承模式。主要功能包括:集中式属性管理、自动属性传播、语义约定支持、多租户标签、部署环境标签、生产级模式。非常适合实现一致的指标标签、管理服务元数据、实现跨服务的指标聚合、支持多环境部署、便于指标过滤和分组、以及建立企业监控标准。通过本示例可以学习全局属性管理、一致性标签实践、以及企业级监控规范。 |
+| [observability/metric/http_client](observability/metric/http_client) | 演示在GoFrame中使用OpenTelemetry和Prometheus收集全面的HTTP客户端指标以监控出站HTTP请求。本示例展示了自动HTTP客户端埋点、请求持续时间直方图、按状态码和方法分类的请求计数指标、错误率跟踪、连接池指标、以及重试尝试监控。主要功能包括:无需代码更改的自动指标收集、详细的请求/响应属性、与GoFrame HTTP客户端集成、可自定义的指标标签、Prometheus导出器配置、生产级可观测性模式。非常适合监控外部API调用、跟踪HTTP客户端性能、调试连接问题、分析请求模式、以及确保微服务架构中出站HTTP通信的可靠性。通过本示例可以学习如何监控HTTP客户端、分析外部依赖、以及优化API调用性能。 |
+| [observability/metric/http_server](observability/metric/http_server) | 演示在GoFrame中使用OpenTelemetry和Prometheus收集全面的HTTP服务器指标以监控入站HTTP请求。本示例展示了自动HTTP服务器埋点、请求延迟直方图、按端点和方法分类的吞吐量指标、HTTP状态码分布、并发请求跟踪、以及错误率监控。主要功能包括:通过中间件自动收集指标、详细的请求属性(路径、方法、状态)、与GoFrame HTTP服务器集成、可自定义的指标桶、Prometheus端点暴露、生产级监控模式。非常适合监控API性能、跟踪服务健康、分析流量模式、识别性能瓶颈、实现SLA监控、以及确保生产环境中HTTP服务的高可用性。通过本示例可以学习如何监控HTTP服务器、分析请求性能、以及构建完整的服务监控体系。 |
+| [observability/metric/meter_attributes](observability/metric/meter_attributes) | 演示在GoFrame中使用OpenTelemetry和Prometheus管理仪表级属性以实现作用域指标标签。本示例展示了仪表特定的属性配置、仪表内的属性作用域、隔离的指标标签、仪表级元数据管理、从仪表到指标的属性继承、以及精细的属性控制。主要功能包括:创建带有自定义属性的仪表、将属性作用域限制在特定指标组、隔离的属性命名空间、自动将属性应用于仪表指标、基于仪表的多租户、生产级模式。非常适合按模块或组件组织指标、实现作用域指标标签、管理多个指标命名空间、隔离指标组之间的属性、构建模块化监控系统、以及为复杂应用建立层次化指标组织。通过本示例可以学习仪表级属性管理、作用域标签、以及层次化指标组织。 |
+| [observability/metric/prometheus](observability/metric/prometheus) | 演示在GoFrame中不使用OpenTelemetry直接集成Prometheus指标以实现轻量级监控解决方案。本示例展示了原生Prometheus客户端库的使用、直接向Prometheus注册表注册指标、counter、gauge、histogram和summary指标类型、自定义指标收集器、用于/metrics端点暴露的HTTP处理器、以及标签管理。主要功能包括:零OpenTelemetry依赖、简单的指标创建和注册、原生Prometheus指标类型、灵活的指标标签、内置HTTP指标端点、生产级模式。非常适合轻量级监控需求、传统Prometheus设置、简化的指标收集、仅需要Prometheus集成的应用、最小依赖占用、以及不需要或不希望使用OpenTelemetry的环境。通过本示例可以学习Prometheus原生API、简化的监控方案、以及轻量级指标收集。 |
+| [observability/trace/grpc-with-db](observability/trace/grpc-with-db) | 演示在GoFrame中使用OpenTelemetry实现gRPC服务与数据库操作的全面分布式跟踪。本示例展示了从gRPC调用到数据库查询的端到端trace埋点、自动gRPC方法和数据库操作跟踪、RPC通信中的trace上下文传播、服务调用与数据库操作之间的span关系、与tracing集成的服务发现、以及分布式系统的性能监控。主要功能包括:全栈gRPC trace可见性、自动数据库查询埋点、服务网格可观测性、分布式事务跟踪、跨服务trace关联、生产级模式。非常适合监控微服务架构性能、调试分布式gRPC系统、优化数据库查询性能、确保服务网格环境的可观测性、以及构建企业级监控解决方案。通过本示例可以学习如何实现gRPC全链路跟踪、分布式系统性能优化、以及构建高可观测的微服务架构。 |
+| [observability/trace/http-with-db](observability/trace/http-with-db) | 演示在GoFrame中使用OpenTelemetry实现HTTP服务与数据库操作的全面分布式跟踪。本示例展示了从HTTP请求到数据库查询的端到端trace埋点、包括MySQL和Redis操作的自动数据库操作跟踪、贯穿整个请求生命周期的trace上下文传播、HTTP处理器与数据库调用之间的span关系、数据库查询的性能监控、以及与GoFrame的ORM和缓存组件集成。主要功能包括:全栈trace可见性、自动数据库查询埋点、慢查询检测、连接池监控、缓存操作跟踪、生产级可观测性。非常适合监控全栈应用性能、调试数据库相关问题、优化查询性能、确保数据驱动应用的端到端可观测性、以及构建全面的监控解决方案。通过本示例可以学习如何实现全链路跟踪、数据库性能优化、以及构建高性能可观测的数据应用。 |
+| [observability/trace/http](observability/trace/http) | 演示在GoFrame中使用OpenTelemetry集成实现HTTP服务的全面分布式链路跟踪。本示例展示了带有自动埋点的HTTP请求和响应跟踪、跨服务边界的trace上下文传播、span创建和属性管理、向OpenTelemetry收集器导出trace数据、与GoFrame HTTP服务器中间件集成、以及分布式trace的可视化。主要功能包括:自动HTTP trace埋点、上下文传播头、自定义span属性、父子span关系、trace采样配置、生产级可观测性模式。非常适合在微服务中实现分布式跟踪、监控HTTP服务性能、调试请求流程、确保云原生应用的可观测性、以及构建生产监控系统。通过本示例可以学习如何在HTTP服务中实现分布式跟踪、OpenTelemetry的最佳实践、以及构建可观测的微服务架构。 |
+| [observability/trace/inprocess-grpc](observability/trace/inprocess-grpc) | 演示在单进程应用中使用GoFrame和高性能gRPC基础的OpenTelemetry导出器实现分布式跟踪。本示例展示了使用gRPC OTLP导出器配置的进程内函数调用跟踪、内部操作的span创建和管理、单进程内的trace上下文传播、高效的基于gRPC的trace数据导出到OpenTelemetry收集器、嵌套函数调用的父子span关系、以及高吞吐量trace数据传输。主要功能包括:高性能gRPC导出器设置、自动span埋点、流式trace导出、高效二进制序列化、生产级性能、企业级模式。非常适合大量trace数据生成、性能关键应用、生产监控系统、需要高效trace导出的应用、以及构建可扩展的可观测性解决方案。通过本示例可以学习如何实现高性能链路跟踪、gRPC导出器的最佳实践、以及构建企业级监控系统。 |
+| [observability/trace/inprocess](observability/trace/inprocess) | 演示在单进程应用中使用GoFrame和基于HTTP的OpenTelemetry导出器实现分布式跟踪以简化可观测性。本示例展示了使用HTTP OTLP导出器配置的进程内函数调用跟踪、内部操作的span创建和管理、单进程内的trace上下文传播、基于HTTP的trace数据导出到OpenTelemetry收集器、嵌套函数调用的父子span关系、以及无需gRPC依赖的简化部署。主要功能包括:轻量级HTTP导出器设置、自动span埋点、内存trace上下文、防火墙友好的HTTP导出、开发友好的配置、生产级模式。非常适合单体应用可观测性、开发和测试环境、简化trace数据导出、仅支持HTTP基础设施的应用、以及学习分布式跟踪概念。通过本示例可以学习如何实现进程内跟踪、简化的可观测性方案、以及轻量级监控部署。 |
+| [observability/trace/otlp](observability/trace/otlp) | 演示在GoFrame中使用OTLP协议通过gRPC和HTTP导出器实现全面的OpenTelemetry链路跟踪数据导出方法。本示例展示了用于trace导出的OTLP（OpenTelemetry协议）配置、gRPC和HTTP导出器的设置与比较、trace数据的序列化和传输、连接管理和重试逻辑、批处理和性能优化、以及与OpenTelemetry收集器的集成。主要功能包括:灵活的导出器配置、高效的trace数据传输、自动批处理和压缩、错误处理和重试机制、生产级导出模式、协议选择指导。非常适合实现生产trace导出、选择合适的导出协议、优化trace数据传输、确保可靠的trace交付、以及构建符合OpenTelemetry标准的企业级可观测性基础设施。通过本示例可以学习OTLP协议的使用、导出器选型、以及构建高效的trace数据导出系统。 |
+| [observability/trace/processes](observability/trace/processes) | 演示使用GoFrame的进程管理方式（包括gcmd和gproc）实现跨多个进程的全面分布式跟踪。本示例展示了进程间的trace上下文传播、带有跟踪的进程生成和生命周期管理、跨进程边界的分布式span关系、多进程架构中的trace关联、带有跟踪支持的不同进程通信模式、以及与GoFrame命令和进程组件的集成。主要功能包括:多进程trace可见性、进程间自动上下文传播、父子进程span关系、进程隔离下trace连续性、生产级多进程模式、企业架构支持。非常适合构建带有可观测性的多进程应用、实现分布式任务处理、监控守护进程和工作进程、确保复杂进程拓扑中的trace连续性、以及创建带有全面跟踪的可扩展多进程系统。通过本示例可以学习多进程链路跟踪、进程间通信与trace传播、以及构建复杂的分布式系统监控。 |
+| [observability/trace/provider](observability/trace/provider) | 演示在GoFrame中配置包括gRPC和HTTP导出器的全面OpenTelemetry链路跟踪provider配置和不同设置模式。本示例展示了trace provider的初始化和配置、用于服务识别的资源属性管理、采样策略配置和选择、基于gRPC和HTTP的导出器设置与比较、用于批处理和简单处理的span处理器配置、以及provider生命周期管理。主要功能包括:灵活的provider配置模式、资源语义约定、多种采样策略(总是、从不、基于父级、基于比例)、导出器协议选择指导、生产级provider设置、企业部署模式。非常适合理解OpenTelemetry provider架构、配置生产trace管道、选择合适的导出器和采样器、优化trace收集性能、以及构建带有适当provider配置的可扩展可观测性基础设施。通过本示例可以学习OpenTelemetry provider的最佳实践、导出器和采样器选型、以及构建企业级链路跟踪系统。 |
+| [practices/injection](practices/injection) | 演示在GoFrame框架中使用do包实现依赖注入模式的全面示例。展示了如何通过接口抽象实现松耦合架构、使用do包管理依赖关系、注册和解析服务实例、单例模式管理、接口注入与实现替换、以及单元测试Mock实现。包含User服务、Gateway网关等实际应用场景，演示了服务分层、接口定义、实现注册、依赖解析等完整流程。非常适合微服务架构开发、可测试代码编写、模块化系统设计、接口驱动开发、以及需要灵活依赖管理的企业级应用。通过本示例可以学习如何构建高可维护、易测试的Go应用程序。 |
+| [practices/mvc-demo-chat](practices/mvc-demo-chat) | 基于GoFrame v2.10.0 MVC模式构建的实时聊天应用，展示WebSocket双向通信、会话管理、HTML模板渲染、昵称唯一性验证和消息限流等功能。 |
+| [practices/quick-demo](practices/quick-demo) | 基于GoFrame v2.10.0的快速入门HTTP RESTful API示例，展示用户CRUD操作、MySQL集成、OpenAPI/Swagger文档自动生成，以及标准项目结构的快速开发实践。 |
+| [practices/user-grpc-service](practices/user-grpc-service) | 演示基于gRPC的用户管理微服务，包含用户增删改查操作。展示Protocol Buffers协议定义、MySQL数据库集成、DAO模式数据访问、Service层业务逻辑封装等特性。适合学习GoFrame框架构建gRPC微服务和掌握微服务架构的开发者。 |
+| [practices/user-http-service](practices/user-http-service) | 演示基于HTTP RESTful API的用户管理服务，包含用户注册、登录、登出等功能。展示Session会话管理、中间件认证授权、OpenAPI文档生成、MySQL数据库集成、DAO模式数据访问等特性。适合学习GoFrame框架构建Web API服务和用户认证系统的开发者。 |
+| [registry/consul](registry/consul) | 演示在GoFrame中全面集成HashiCorp Consul服务注册中心实现企业级服务发现和健康监控。本示例展示了向Consul代理注册服务包括健康检查配置、使用过滤器和基于标签的查询进行服务发现、内置健康监控和自动移除不健康服务、服务元数据和版本管理支持、多数据中心服务发现、以及与GoFrame服务器和客户端组件集成。主要功能包括:企业服务注册中心、自动健康检查执行、DNS和HTTP服务发现接口、负载均衡器集成、服务网格兼容性、生产级模式。适合构建需要强大服务发现的微服务、实现企业服务网格、确保服务健康监控、以及实现跨多数据中心的动态服务注册。 |
+| [registry/etcd](registry/etcd) | 演示在GoFrame中全面集成Etcd服务注册中心实现分布式服务发现和注册。本示例展示了使用自动心跳机制向Etcd注册服务、服务发现和监听实时更新、基于TTL的服务健康管理、服务元数据和端点配置、关闭时自动服务注销、以及与GoFrame服务器和客户端组件集成。主要功能包括:分布式服务注册中心、通过watch机制实现实时服务更新、健康检查集成、负载均衡器集成、自动故障转移支持、生产级模式。适合构建需要动态服务发现的云原生微服务、实现服务网格架构、通过自动服务注册确保高可用性、以及实现零停机部署。 |
+| [registry/file](registry/file) | 演示在GoFrame框架中实现基于文件系统的服务注册与发现机制。本示例展示了如何使用本地文件系统作为轻量级注册中心，支持服务自动注册、服务列表查询、服务实例管理、配置文件存储、以及无需外部依赖的简单部署。主要功能包括:本地文件存储服务信息、JSON/YAML格式服务描述、自动文件监听和刷新、多实例注册管理、简单的配置管理、零外部依赖部署。适合开发环境快速测试、单机或小型应用部署、学习和演示注册中心概念、离线环境的服务管理、以及不需要复杂注册中心的简单应用场景。 |
+| [registry/nacos](registry/nacos) | 演示在GoFrame中全面集成阿里巴巴Nacos服务注册中心实现动态服务管理和配置。本示例展示了使用命名空间和分组隔离向Nacos注册服务、使用实例过滤和选择策略进行服务发现、内置健康监控和心跳机制、服务元数据和基于权重的负载均衡、与Nacos配置中心集成、以及无缝的GoFrame组件集成。主要功能包括:集中式服务注册中心、实时服务状态更新、健康检查自动化、加权负载均衡支持、基于命名空间的服务隔离、生产级模式。适合在阿里云上构建云原生微服务、实现带配置管理的动态服务发现、确保服务健康和可用性、以及实现企业级服务治理。 |
+| [registry/polaris](registry/polaris) | 演示在GoFrame中全面集成腾讯云Polaris服务注册中心实现服务网格和流量管理。本示例展示了使用高级配置选项向Polaris注册服务、与熔断器和限流集成的服务发现、健康检查配置和自动实例隔离、服务路由和流量管理、与Polaris网格集成实现统一治理、以及无缝的GoFrame组件集成。主要功能包括:服务网格注册中心、流量控制策略、熔断器模式、基于健康的路由、金丝雀部署支持、生产级模式。适合在腾讯云上构建云原生微服务、实现服务网格架构、通过流量管理确保高可用性、以及实现带统一控制面板的高级服务治理。 |

package/skills/goframe-v2/examples/balancer/http/README.MD

@@ -0,0 +1,91 @@
+---
+title: HTTP Service
+slug: /examples/balancer/http
+keywords: [load balancer, http, service discovery, goframe]
+description: Demonstrates HTTP service load balancing implementation using GoFrame with etcd-based service registration and discovery. This example showcases client-side load balancing with round-robin strategy, automatic service discovery, and distributed request routing across multiple HTTP server instances. Features include service registration using etcd, dynamic service discovery, configurable load balancing strategies, and seamless integration with GoFrame's HTTP server and client components for building scalable microservices architectures.
+hide_title: true
+---
+
+# Load Balancer - HTTP Service Example
+
+## Description
+
+This example demonstrates how to implement HTTP service load balancing with `GoFrame`. It shows:
+- Service registration using `etcd`
+- Client-side load balancing
+- Round-robin load balancing strategy
+- HTTP service communication
+
+## Requirements
+
+- [Go](https://golang.org/dl/) `1.22` or higher
+- [Git](https://git-scm.com/downloads)
+- [GoFrame](https://goframe.org)
+
+## Structure
+
+```text
+.
+├── client/           # HTTP client implementation with load balancing
+│   └── client.go     # Client code with round-robin balancer
+├── server/           # HTTP server implementation
+│   └── server.go     # Server code with service registration
+├── go.mod            # Go module file
+└── go.sum            # Go module checksums
+```
+
+## Prerequisites
+
+1. Running `etcd` server:
+   ```bash
+   # Using docker
+   docker run -d --name etcd-server \
+      --publish 2379:2379 \
+      --publish 2380:2380 \
+      --env ALLOW_NONE_AUTHENTICATION=yes \
+      bitnami/etcd:latest
+   ```
+
+## Usage
+
+1. Start multiple server instances (use random different ports):
+   ```bash
+   # Terminal 1
+   cd server
+   go run server.go
+
+   # Terminal 2
+   cd server
+   go run server.go
+
+   # Terminal 3
+   cd server
+   go run server.go
+   ```
+
+2. Run the client to test load balancing:
+   ```bash
+   cd client
+   go run client.go
+   ```
+
+## Implementation Details
+
+1. Server Implementation (`server/server.go`):
+   - HTTP server setup using `GoFrame`
+   - Service registration with `etcd`
+   - Simple HTTP endpoint that returns "Hello world"
+   - Automatic service discovery registration
+
+2. Client Implementation (`client/client.go`):
+   - Service discovery using `etcd`
+   - Round-robin load balancing strategy
+   - Multiple request demonstration
+   - Automatic service discovery and load balancing
+
+## Notes
+
+- The example uses `etcd` for service registration and discovery
+- Round-robin load balancing is implemented for demonstration
+- The client automatically handles service discovery and load balancing
+- Multiple server instances can be started to demonstrate load distribution

package/skills/goframe-v2/examples/balancer/http/README.ZH.MD

@@ -0,0 +1,44 @@
+---
+title: HTTP负载均衡
+slug: /examples/balancer/http
+keywords: [负载均衡, http, 服务发现, goframe]
+description: 演示如何使用GoFrame框架结合etcd实现HTTP服务的负载均衡功能。本示例展示了基于客户端的负载均衡实现，采用轮询策略进行请求分发，支持自动服务发现和动态路由。主要功能包括：使用etcd进行服务注册与发现、客户端轮询负载均衡策略、多服务实例请求分发、与GoFrame的HTTP服务器和客户端组件无缝集成，适用于构建高可用、可扩展的微服务架构系统。通过本示例可以学习如何在分布式环境中实现服务负载均衡和服务发现机制。
+hide_title: true
+---
+
+# HTTP 服务负载均衡示例
+
+## 介绍
+
+本示例展示了如何在 `GoFrame` 应用程序中实现 HTTP 服务的负载均衡。主要演示：
+- 使用 `etcd` 配置负载均衡器
+- 服务注册和服务发现
+- 请求路由和负载分发
+
+## 目录结构
+
+```text
+.
+├── server/         # HTTP 服务器
+├── client/         # HTTP 客户端
+├── go.mod          # Go 模块文件
+└── go.sum          # Go 模块校验
+```
+
+## 环境要求
+
+- [Go](https://golang.org/dl/) `1.22` 或更高版本
+- [Git](https://git-scm.com/downloads)
+- [GoFrame](https://goframe.org)
+
+## 使用说明
+
+1. 启动服务器：
+   ```bash
+   go run server/main.go
+   ```
+
+2. 在另一个终端启动客户端：
+   ```bash
+   go run client/main.go
+   ```

package/skills/goframe-v2/examples/balancer/http/client/client.go

@@ -0,0 +1,48 @@
+// Copyright GoFrame Author(https://goframe.org). All Rights Reserved.
+//
+// This Source Code Form is subject to the terms of the MIT License.
+// If a copy of the MIT was not distributed with this file,
+// You can obtain one at https://github.com/gogf/gf.
+
+// Package main implements a HTTP client with load balancing capabilities.
+// It demonstrates how to:
+// 1. Set up service discovery using etcd
+// 2. Configure round-robin load balancing
+// 3. Make HTTP requests to distributed services
+package main
+
+import (
+	"github.com/gogf/gf/v2/frame/g"
+	"github.com/gogf/gf/v2/net/gsel"
+	"github.com/gogf/gf/v2/net/gsvc"
+	"github.com/gogf/gf/v2/os/gctx"
+
+	"github.com/gogf/gf/contrib/registry/etcd/v2"
+)
+
+func main() {
+	// Initialize etcd registry with the etcd server address
+	// This enables service discovery for the client
+	gsvc.SetRegistry(etcd.New(`127.0.0.1:2379`))
+
+	// Set up round-robin load balancing strategy
+	// This ensures requests are distributed evenly across available servers
+	gsel.SetBuilder(gsel.NewBuilderRoundRobin())
+
+	client := g.Client()
+	client.SetDiscovery(gsvc.GetRegistry())
+
+	// Make 10 HTTP requests to demonstrate load balancing
+	// Each request will be routed to a different server instance in round-robin fashion
+	for i := 0; i < 10; i++ {
+		// Create a new context for each request
+		ctx := gctx.New()
+
+		// Make HTTP request to the service using its service name
+		// The client automatically handles service discovery and load balancing
+		res := client.GetContent(ctx, `http://hello.svc/`)
+
+		// Log the response from the server
+		g.Log().Info(ctx, res)
+	}
+}

package/skills/goframe-v2/examples/balancer/http/go.mod

@@ -0,0 +1,53 @@
+module main
+
+go 1.23.0
+
+require (
+	github.com/gogf/gf/contrib/registry/etcd/v2 v2.10.0
+	github.com/gogf/gf/v2 v2.10.0
+)
+
+require (
+	github.com/BurntSushi/toml v1.5.0 // indirect
+	github.com/clbanning/mxj/v2 v2.7.0 // indirect
+	github.com/coreos/go-semver v0.3.0 // indirect
+	github.com/coreos/go-systemd/v22 v22.3.2 // indirect
+	github.com/emirpasic/gods/v2 v2.0.0-alpha // indirect
+	github.com/fatih/color v1.18.0 // indirect
+	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/gorilla/websocket v1.5.3 // indirect
+	github.com/grokify/html-strip-tags-go v0.1.0 // indirect
+	github.com/magiconair/properties v1.8.10 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-runewidth v0.0.16 // indirect
+	github.com/olekukonko/errors v1.1.0 // indirect
+	github.com/olekukonko/ll v0.0.9 // indirect
+	github.com/olekukonko/tablewriter v1.1.0 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	go.etcd.io/etcd/api/v3 v3.5.17 // indirect
+	go.etcd.io/etcd/client/pkg/v3 v3.5.17 // indirect
+	go.etcd.io/etcd/client/v3 v3.5.17 // indirect
+	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
+	go.opentelemetry.io/otel v1.38.0 // indirect
+	go.opentelemetry.io/otel/metric v1.38.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.38.0 // indirect
+	go.opentelemetry.io/otel/trace v1.38.0 // indirect
+	go.uber.org/atomic v1.7.0 // indirect
+	go.uber.org/multierr v1.6.0 // indirect
+	go.uber.org/zap v1.17.0 // indirect
+	golang.org/x/net v0.40.0 // indirect
+	golang.org/x/sys v0.35.0 // indirect
+	golang.org/x/text v0.25.0 // indirect
+	google.golang.org/genproto v0.0.0-20230822172742-b8732ec3820d // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20230822172742-b8732ec3820d // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20230822172742-b8732ec3820d // indirect
+	google.golang.org/grpc v1.59.0 // indirect
+	google.golang.org/protobuf v1.33.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)