@colin4k1024/tsp 2.4.0

package/skills/goframe-v2/references//345/274/200/345/217/221/345/267/245/345/205/267//351/241/271/347/233/256/345/210/233/345/273/272-init.md

@@ -0,0 +1,218 @@
+:::tip
+从`v2`版本开始，项目的创建不再依赖远端获取，仓库模板已经通过 [资源管理](../核心组件/资源管理/资源管理.md) 的方式内置到了工具二进制文件中，因此项目创建速度非常迅速，无需网络访问。
+:::
+
+## 使用方式
+
+```bash
+$ gf init -h
+USAGE
+    gf init ARGUMENT [OPTION]
+
+ARGUMENT
+    NAME    name for the project. It will create a folder with NAME in current directory.
+            The NAME will also be the module name for the project.
+
+OPTION
+    -m, --mono          initialize a mono-repo instead a single-repo
+    -a, --monoApp       initialize a mono-repo-app instead a single-repo
+    -u, --update        update to the latest goframe version
+    -g, --module        custom go module
+    -r, --repo          remote repository URL for template download
+    -s, --select        enable interactive version selection for remote template
+    -i, --interactive   enable interactive mode to select template
+    -h, --help          more information about this command
+
+EXAMPLE
+    gf init my-project
+    gf init my-mono-repo -m
+    gf init my-mono-repo -a
+    gf init my-project -u
+    gf init my-project -g "github.com/myorg/myproject"
+    gf init -r github.com/gogf/template-single my-project
+    gf init -r github.com/gogf/examples/httpserver/jwt my-jwt
+    gf init -r github.com/gogf/gf/cmd/gf/v2@v2.9.7 mygf
+    gf init -r github.com/gogf/gf/cmd/gf/v2 mygf -s
+    gf init -i
+```
+
+我们可以使用`init`命令在当前目录生成一个示例的`GoFrame`空框架项目，并可给定项目名称参数。生成的项目目录结构根据业务项目具体情况可自行调整。生成的目录结构详细介绍请参考 [工程目录设计](../框架设计/工程开发设计/工程目录设计.md) 章节。
+
+:::tip 提示
+- `GoFrame`框架开发推荐统一使用官方的`go module`特性进行依赖包管理，因此空项目根目录下也有一个`go.mod`文件。
+
+- 工程目录采用了通用化的设计，实际项目中可以根据项目需要适当增减模板给定的目录。例如，没有`kubernetes`部署需求的场景，直接删除对应`deploy`目录即可。
+:::
+
+## 选项说明
+
+| 选项 | 缩写 | 说明 |
+|---|---|---|
+| `--mono` | `-m` | 创建`MonoRepo`（大仓）项目，而非默认的`SingleRepo`项目 |
+| `--monoApp` | `-a` | 在`MonoRepo`大仓中创建一个子应用项目 |
+| `--update` | `-u` | 项目创建后自动升级`GoFrame`依赖到最新版本 |
+| `--module` | `-g` | 自定义`Go`模块路径，不指定时默认使用项目名称 |
+| `--repo` | `-r` | 指定远程仓库`URL`作为项目模板来源 |
+| `--select` | `-s` | 配合`-r`使用，启用交互式版本选择 |
+| `--interactive` | `-i` | 启用完整的交互式引导模式创建项目 |
+
+## 模板类型
+
+`gf init`命令支持三种内置项目模板：
+
+| 模板类型 | 选项 | 说明 |
+|---|---|---|
+| `SingleRepo` | 默认 | 单仓项目，适用于大多数独立项目开发场景 |
+| `MonoRepo` | `-m` | 大仓项目，适用于微服务架构的统一仓库管理 |
+| `MonoRepoApp` | `-a` | 大仓子应用，在已有`MonoRepo`仓库中创建新的子服务 |
+
+## 使用示例
+
+### 在当前目录下初始化项目
+
+使用`.`作为项目名称，直接在当前目录下初始化项目，模块名称默认使用当前目录名称。
+
+```bash
+$ gf init .
+initializing...
+initialization done!
+you can now run 'gf run main.go' to start your journey, enjoy!
+```
+
+### 创建一个指定名称的项目
+
+指定项目名称后，会在当前目录下创建一个同名文件夹，模块名称默认与项目名称一致。
+
+```bash
+$ gf init myapp
+initializing...
+initialization done!
+you can now run 'cd myapp && gf run main.go' to start your journey, enjoy!
+```
+
+### 创建一个`MonoRepo`项目
+
+默认情况下创建的是`SingleRepo`项目，若有需要也可以创建一个`MonoRepo`（大仓）项目，通过使用`-m`选项即可。
+
+```bash
+$ gf init mymono -m
+initializing...
+initialization done!
+```
+
+关于大仓的介绍请参考章节： [微服务大仓管理模式](../框架设计/工程开发设计/微服务大仓管理模式.md)
+
+### 创建一个`MonoRepoApp`项目
+
+若需要在`MonoRepo`（大仓）下创建一个子应用，在大仓项目根目录下，给定需要生成的项目路径，并使用`-a`选项即可。
+
+```bash
+$ gf init app/user -a
+initializing...
+initialization done!
+```
+
+### 自定义`Go`模块路径
+
+默认情况下项目的`go.mod`中的模块名称(`module`)与项目文件夹名称一致。如果需要自定义`Go`模块路径（例如使用完整的仓库地址），可以通过`-g`选项指定。
+
+```bash
+$ gf init myapp -g "github.com/myorg/myproject"
+initializing...
+initialization done!
+you can now run 'cd myapp && gf run main.go' to start your journey, enjoy!
+```
+
+执行后生成的`go.mod`文件中模块路径为`github.com/myorg/myproject`，项目中所有相关的`import`路径也会自动替换为该模块路径。
+
+### 创建项目并升级`GoFrame`版本
+
+使用`-u`选项可以在项目创建完成后自动将`GoFrame`依赖升级到**最新版本**，并执行`go mod tidy`。
+
+```bash
+$ gf init myapp -u
+initializing...
+initialization done!
+you can now run 'cd myapp && gf run main.go' to start your journey, enjoy!
+```
+
+## 远程模板
+
+除了使用内置模板外，`gf init`还支持从远程仓库拉取模板来创建项目，通过`-r`选项指定远程仓库地址。远程模板支持以下两种来源：
+
+- **`Go`模块**：通过`Go`模块代理下载，支持使用`@version`语法指定版本。
+- **`Git`仓库子目录**：通过`git sparse checkout`下载指定子目录，适合从示例仓库中提取特定项目。
+
+:::tip 注意
+使用远程模板时需要确保本地已安装`Go`环境。如果使用`Git`仓库子目录方式，还需要安装`git`工具。远程模板模式下，目标目录必须为空，否则会返回错误。
+:::
+
+### 使用远程`Go`模块模板
+
+```bash
+$ gf init -r github.com/gogf/template-single my-project
+```
+
+### 使用远程仓库子目录模板
+
+可以从一个`Git`仓库的子目录中提取模板，适合从示例仓库中获取特定类型的项目模板。
+
+```bash
+$ gf init -r github.com/gogf/examples/httpserver/jwt my-jwt
+```
+
+### 指定模板版本
+
+可以通过`@version`语法指定模板的版本号。
+
+```bash
+$ gf init -r github.com/gogf/gf/cmd/gf/v2@v2.9.7 mygf
+```
+
+### 交互式选择模板版本
+
+使用`-s`选项配合`-r`选项，可以在命令执行时列出可用版本供用户选择。工具会展示最新的版本列表（按版本号倒序排列），用户可以通过编号选择或直接输入版本号。
+
+```bash
+$ gf init -r github.com/gogf/gf/cmd/gf/v2 mygf -s
+```
+
+## 交互式模式
+
+使用`-i`选项可以启用完整的交互式引导模式，工具会分步引导用户完成项目创建的所有配置。
+
+```bash
+$ gf init -i
+```
+
+交互式模式分为两个阶段：
+
+**第一步：选择初始化方式**
+
+- **内置模板**（默认）：使用工具内置的模板快速创建项目，无需网络访问。
+- **远程模板**：从远程仓库拉取模板创建项目。
+
+**第二步（内置模板方式）：**
+
+- 选择项目类型：`SingleRepo`/`MonoRepo`/`MonoRepoApp`
+- 输入项目名称
+- 输入`Go`模块路径（可选，默认使用项目名称）
+- 选择是否升级到最新`GoFrame`版本
+
+**第二步（远程模板方式）：**
+
+- 选择预设模板（`template-single`、`template-mono`）或输入自定义仓库`URL`
+- 输入项目名称
+- 输入`Go`模块路径（可选）
+- 选择是否升级依赖
+
+:::info
+交互式模式对新手用户非常友好，如果不确定各参数的用法，推荐使用该模式完成项目创建。
+:::
+
+## 注意事项
+
+- 当目标目录已存在且非空时，使用内置模板会提示是否覆盖；使用远程模板则会直接报错，要求目标目录为空。
+- 使用`.`作为项目名称时，会直接在当前目录下初始化项目，模块名默认取当前目录名称。
+- `-u`选项在内置模板模式下会升级`GoFrame`相关依赖；在远程模板模式下会升级所有依赖并执行`go mod tidy`。
+- 项目创建完成后，所有生成的`.go`文件中的`import`路径会自动替换为实际的模块路径。

package/skills/goframe-v2/references//345/276/256/346/234/215/345/212/241/345/274/200/345/217/221//345/267/245/347/250/213/347/256/241/347/220/206.md

@@ -0,0 +1,53 @@
+## 基本介绍
+
+基于微服务开发的工程目录采用统一的框架工程目录结构，具体请参考章节： [工程目录设计🔥](../框架设计/工程开发设计/工程目录设计.md)
+
+我们这里以项目 [https://github.com/gogf/gf-demo-grpc](https://github.com/gogf/gf-demo-grpc) 为例说明。
+
+## 协议文件
+
+协议文件定义在 `manifest/protobuf` 目录下。协议文件的目录路径遵循规则： `模块名/版本号/xxx.proto`，其中版本号采用 `v1`/ `v2` 的形式进行管理，便于维护接口的版本兼容性。
+
+其中，涉及数据表结构的 `protobuf` 文件，由框架开发工具自动生成后存放在 `manifest/pbentity` 目录下。
+
+## 接口文件
+
+通过 `proto` 协议文件编译生成的接口文档统一存放在 `api` 目录下。
+
+## 开发工具
+
+### 生成数据表结构
+
+我们可以通过 `gf gen pbentity` 命令（或使用 `make pbentity` ）自动根据数据库中的数据表结构生成对应的 `protobuf` 协议文件。该命令会读取数据库表结构信息，并自动生成符合 protobuf 规范的消息定义文件。命令详细介绍请参考章节： [数据表PB-gen pbentity](../开发工具/代码生成-gen/数据表PB-gen%20pbentity.md)
+
+### 编译 `proto` 协议文件
+
+框架提供了 `gf gen pb` 命令（或使用 `make pb` ）自动编译 `proto` 协议文件，并生成对应的接口文件以及控制器文件。该命令会扫描项目中的所有 proto 文件，使用 protoc 编译器生成 Go 语言的 gRPC 接口代码，并自动创建对应的控制器模板文件。
+
+## 服务的启动
+
+服务的启动控制通过 `cmd` 目录进行维护，例如： [https://github.com/gogf/gf-demo-grpc/blob/main/internal/cmd/cmd.go](https://github.com/gogf/gf-demo-grpc/blob/main/internal/cmd/cmd.go)
+
+在 cmd 文件中，我们需要初始化 gRPC 服务器，配置服务地址和端口，并注册所有的服务实现。
+
+## 接口的实现与注册
+
+控制器用于实现 `proto` 文件中定义的接口。控制器文件可以通过 `gf gen pb` 命令自动生成，同时会自动生成 `Register` 方法，该方法用于将具体的接口实现注册到 gRPC 服务对象中。
+
+注册方法示例：
+
+在服务启动时进行注册：
+
+## 标签注入与数据校验
+
+### 标签自动注入
+
+使用 `gf gen pb` 命令（或 `make pb` ）进行 `proto` 文件编译时，支持自动的标签注入功能。只需要通过注释的形式写到 `proto` 文件中，这些注释将会自动作为 `dc` 标签嵌入到生成的结构体属性中。如果注释规则形如 `xxx:yyy`，那么将会自动生成对应的 `xxx` 标签。例如：
+
+生成后的结构体将包含相应的标签：
+
+需要注意，在 `gRPC` 协议中，由于输入输出均采用结构体形式，因此无法实现像 `HTTP` 服务那样的默认值特性。
+
+### 数据校验插件
+
+数据校验插件会根据标签中设置的规则对请求进行自动校验。该插件需要在服务端通过拦截器的形式手动引入：

package/skills/goframe-v2/references//345/276/256/346/234/215/345/212/241/345/274/200/345/217/221//345/276/256/346/234/215/345/212/241/345/274/200/345/217/221.md

@@ -0,0 +1,284 @@
+## 基本介绍
+
+`GoFrame` 框架从 `v2.4` 版本开始全面支持微服务模式开发，提供了常用的微服务组件、开发工具和开发教程，帮助开发团队快速实现微服务架构转型。
+
+## 简单示例
+
+`GoFrame` 的微服务组件采用低耦合和通用化设计，组件化的使用方式支持大部分的微服务通信协议。在官方文档中，我们以 `HTTP` 和 `gRPC` 协议为示例，介绍微服务的开发以及组件工具的使用。由于 `HTTP Web` 开发已经有比较丰富完善的独立章节介绍，因此微服务章节主要以 `gRPC` 为例进行讲解。
+
+### `HTTP` 微服务示例
+
+[https://github.com/gogf/gf/tree/master/example/registry/file](https://github.com/gogf/gf/tree/master/example/registry/file)
+
+#### `server.go`
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/contrib/registry/file/v2"
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+    "github.com/gogf/gf/v2/net/gsvc"
+    "github.com/gogf/gf/v2/os/gfile"
+)
+
+func main() {
+    gsvc.SetRegistry(file.New(gfile.Temp("gsvc")))
+
+    s := g.Server(`hello.svc`)
+    s.BindHandler("/", func(r *ghttp.Request) {
+        g.Log().Info(r.Context(), `request received`)
+        r.Response.Write(`Hello world`)
+    })
+    s.Run()
+}
+```
+
+可以看到，一个 `HTTP` 微服务端和普通的 `Web Server` 基本一致，但是顶部多了一行代码：
+
+```go
+gsvc.SetRegistry(file.New(gfile.Temp("gsvc")))
+```
+
+这行代码用于启用并配置当前服务使用的服务注册发现组件。在该示例中使用的 `file.New(gfile.Temp("gsvc"))` 是基于本地文件系统的服务注册发现组件，其中的 `gfile.Temp("gsvc")` 指定了存放服务信息文件的路径。例如在 `Linux`/ `MacOS` 系统下，该路径指向 `/tmp/gsvc` 目录。
+
+:::warning
+基于文件系统的注册发现组件仅适用于本地开发和测试，不支持跨节点通信。
+:::
+
+在生产环境中，我们需要使用分布式的服务注册发现组件，例如 `etcd`、 `polaris`、 `zookeeper` 等。框架的社区组件库中已经提供了这些常用服务注册发现组件的实现。
+
+在该示例中，我们为 `Server` 设置了名称 `hello.svc`，这是该服务在微服务架构中的唯一标识。服务名称用于服务间的识别和通信，是微服务治理的基础。当启用服务注册组件后， `HTTP Server` 在运行时会自动将自己的访问地址（IP和端口）注册到服务注册中心，使得其他服务能够通过服务名称发现并访问该服务。
+
+#### `client.go`
+
+```go
+package main
+
+import (
+    "time"
+
+    "github.com/gogf/gf/contrib/registry/file/v2"
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/gsvc"
+    "github.com/gogf/gf/v2/os/gctx"
+    "github.com/gogf/gf/v2/os/gfile"
+)
+
+func main() {
+    gsvc.SetRegistry(file.New(gfile.Temp("gsvc")))
+
+    client := g.Client()
+    for i := 0; i < 10; i++ {
+        ctx := gctx.New()
+        res, err := client.Get(ctx, `http://hello.svc/`)
+        if err != nil {
+            panic(err)
+        }
+        g.Log().Debug(ctx, res.ReadAllString())
+        res.Close()
+        time.Sleep(time.Second)
+    }
+}
+```
+
+客户端通过 `g.Client()` 创建一个 `HTTP Client` 对象，并通过 `http://hello.svc/` 地址访问服务端。其中的 `hello.svc` 是之前服务端绑定的微服务名称。当客户端使用微服务名称进行访问时，服务注册发现组件会自动在底层进行服务发现，查询该服务名称对应的实际服务地址，然后建立连接进行通信。
+
+#### 执行结果
+
+先执行 `server.go` 启动服务端，然后再执行 `client.go` 通过服务名称请求服务。
+
+执行后，客户端输出：
+
+```bash
+$ go run client.go
+2023-03-14 20:22:10.006 [DEBU] {8054f3a48c484c1760fb416bb3df20a4} Hello world
+2023-03-14 20:22:11.007 [DEBU] {6831cae08c484c1761fb416b9d4df851} Hello world
+2023-03-14 20:22:12.008 [DEBU] {9035761c8d484c1762fb416b1e648b81} Hello world
+2023-03-14 20:22:13.011 [DEBU] {a05a32588d484c1763fb416bc19ff667} Hello world
+2023-03-14 20:22:14.012 [DEBU] {40fdea938d484c1764fb416b8459fc43} Hello world
+2023-03-14 20:22:15.014 [DEBU] {686c9acf8d484c1765fb416b3697d369} Hello world
+2023-03-14 20:22:16.015 [DEBU] {906a470b8e484c1766fb416b85b9867e} Hello world
+2023-03-14 20:22:17.017 [DEBU] {28c7fd468e484c1767fb416b86e5557f} Hello world
+2023-03-14 20:22:18.018 [DEBU] {90d2ad828e484c1768fb416bfcde738f} Hello world
+2023-03-14 20:22:19.019 [DEBU] {d05559be8e484c1769fb416baad06f23} Hello world
+```
+
+服务端输出：
+
+```bash
+$ go run server.go
+2023-03-14 20:20:06.364 [INFO] pid[96421]: http server started listening on [:61589]
+2023-03-14 20:20:06.364 [INFO] openapi specification is disabled
+2023-03-14 20:20:06.364 [DEBU] service register: &{Head: Deployment: Namespace: Name:hello.svc Version: Endpoints:10.35.12.81:61589 Metadata:map[insecure:true protocol:http]}
+
+   SERVER   | DOMAIN  | ADDRESS | METHOD | ROUTE |                             HANDLER                             |    MIDDLEWARE
+------------|---------|---------|--------|-------|-----------------------------------------------------------------|--------------------
+  hello.svc | default | :61589  | ALL    | /     | main.main.func1                                                 |
+------------|---------|---------|--------|-------|-----------------------------------------------------------------|--------------------
+  hello.svc | default | :61589  | ALL    | /*    | github.com/gogf/gf/v2/net/ghttp.internalMiddlewareServerTracing | GLOBAL MIDDLEWARE
+------------|---------|---------|--------|-------|-----------------------------------------------------------------|--------------------
+
+2023-03-14 20:22:10.006 [INFO] {8054f3a48c484c1760fb416bb3df20a4} request received
+2023-03-14 20:22:11.007 [INFO] {6831cae08c484c1761fb416b9d4df851} request received
+2023-03-14 20:22:12.008 [INFO] {9035761c8d484c1762fb416b1e648b81} request received
+2023-03-14 20:22:13.010 [INFO] {a05a32588d484c1763fb416bc19ff667} request received
+2023-03-14 20:22:14.012 [INFO] {40fdea938d484c1764fb416b8459fc43} request received
+2023-03-14 20:22:15.013 [INFO] {686c9acf8d484c1765fb416b3697d369} request received
+2023-03-14 20:22:16.015 [INFO] {906a470b8e484c1766fb416b85b9867e} request received
+2023-03-14 20:22:17.016 [INFO] {28c7fd468e484c1767fb416b86e5557f} request received
+2023-03-14 20:22:18.017 [INFO] {90d2ad828e484c1768fb416bfcde738f} request received
+2023-03-14 20:22:19.019 [INFO] {d05559be8e484c1769fb416baad06f23} request received
+```
+
+### `GRPC` 微服务示例
+
+[https://github.com/gogf/gf/tree/master/example/rpc/grpcx/basic](https://github.com/gogf/gf/tree/master/example/rpc/grpcx/basic)
+
+#### `helloworld.proto`
+
+`gRPC` 和 `HTTP` 协议的一个显著区别是， `gRPC` 需要通过 `protobuf` 来定义 `API` 接口和数据结构。 `Protobuf` 是一种语言无关、平台无关的可扩展序列化数据结构，相比 `JSON` 和 `XML` 更小更快，是 `gRPC` 的核心特性。
+
+```
+syntax = "proto3";
+
+package protobuf;
+
+option go_package = "github.com/gogf/gf/grpc/example/helloworld/protobuf";
+
+// The greeting service definition.
+service Greeter {
+  // Sends a greeting
+  rpc SayHello (HelloRequest) returns (HelloReply) {}
+}
+
+// The request message containing the user's name.
+message HelloRequest {
+  string name = 1;
+}
+
+// The response message containing the greetings
+message HelloReply {
+  string message = 1;
+}
+```
+
+以上 `protobuf` 文件通过以下命令执行编译（请提前安装 `protoc` 工具）：
+
+```
+gf gen pb
+```
+
+将会生成对应的 `proto go` 数据结构文件以及 `grpc` 接口文件：
+
+```
+helloworld.pb.go
+helloworld_grpc.pb.go
+```
+
+#### `controller.go`
+
+控制器用于实现 `proto` 文件中定义的接口方法。如果使用框架的标准化工程目录结构，该控制器代码文件也可以由框架的 `gf gen pb` 工具自动生成，开发者只需要填充对应方法的具体实现逻辑即可。
+
+```go
+type Controller struct {
+    protobuf.UnimplementedGreeterServer
+}
+
+func Register(s *grpcx.GrpcServer) {
+    protobuf.RegisterGreeterServer(s.Server, &Controller{})
+}
+
+// SayHello implements helloworld.GreeterServer
+func (s *Controller) SayHello(ctx context.Context, in *protobuf.HelloRequest) (*protobuf.HelloReply, error) {
+    return &protobuf.HelloReply{Message: "Hello " + in.GetName()}, nil
+}
+```
+
+#### `config.yaml`
+
+服务端配置文件，在该配置文件中指定了微服务的名称为 `demo`。微服务名称是服务间通信的唯一标识符。当未显式配置服务端的监听端口时，服务端会自动监听一个可用的本地端口。在微服务模式下，由于使用服务名称进行通信，服务端端口通常不需要显式指定，采用随机监听即可。
+
+```
+grpc:
+  name:            "demo"
+  logPath:          "./log"
+  logStdout:        true
+  errorLogEnabled:  true
+  accessLogEnabled: true
+  errorStack:       true
+```
+
+#### `server.go`
+
+`gRPC` 服务端的启动代码。当未显式指定服务端使用的服务注册发现组件时，服务端默认使用基于文件系统的注册发现组件，该组件仅适用于单机测试。其中的 `controller.Register(s)` 调用了我们通过工具生成的控制器注册方法，将具体的接口实现注册到服务端中。
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/contrib/rpc/grpcx/v2"
+    "github.com/gogf/gf/example/rpc/grpcx/basic/controller"
+)
+
+func main() {
+    s := grpcx.Server.New()
+    controller.Register(s)
+    s.Run()
+}
+```
+
+#### `client.go`
+
+`gRPC` 客户端的调用代码。在创建连接时需要指定服务端服务的名称。这里的服务名称为 `demo`，对应的是上面配置文件中设置的微服务名称。当未显式指定客户端使用的服务注册发现组件时，客户端默认使用基于文件系统的注册发现组件，该组件仅适用于单机测试。
+
+```go
+package main
+
+import (
+    "github.com/gogf/gf/contrib/rpc/grpcx/v2"
+    "github.com/gogf/gf/example/rpc/grpcx/basic/protobuf"
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/os/gctx"
+)
+
+func main() {
+    var (
+        ctx    = gctx.New()
+        conn   = grpcx.Client.MustNewGrpcClientConn("demo")
+        client = protobuf.NewGreeterClient(conn)
+    )
+    res, err := client.SayHello(ctx, &protobuf.HelloRequest{Name: "World"})
+    if err != nil {
+        g.Log().Error(ctx, err)
+        return
+    }
+    g.Log().Debug(ctx, "Response:", res.Message)
+}
+```
+
+#### 执行结果
+
+服务端输出：
+
+可以看到，服务端输出了一些 `DEBU` 级别的调试信息，用于显示服务注册的详细信息。由于没有显式指定服务端的监听端口，这里随机监听了本地端口 `64517`。
+
+```bash
+$ go run server.go
+2023-03-14 20:50:58.465 [DEBU] set default registry using file registry as no custom registry set
+2023-03-14 20:50:58.466 [DEBU] service register: &{Head: Deployment: Namespace: Name:demo Version: Endpoints:10.35.12.81:64517 Metadata:map[protocol:grpc]}
+2023-03-14 20:50:58.466 [INFO] pid[98982]: grpc server started listening on [:64517]
+2023-03-14 20:52:37.059 {9898c809364a4c17da79e47f3e6c3b8f} /protobuf.Greeter/SayHello, 0.003ms, name:"World", message:"Hello World"
+```
+
+客户端输出：
+
+客户端通过微服务名称访问，并成功接收到了服务端的响应。需要注意的是，客户端和服务端日志中的链路跟踪 ID（ `TraceID`）是相同的（ `9898c809364a4c17da79e47f3e6c3b8f`），这表明它们属于同一个请求链路。 `GoFrame` 框架的微服务特性默认开启了链路跟踪能力，方便开发者进行请求链的追踪和问题排查。
+
+```bash
+$ go run client.go
+2023-03-14 20:52:37.060 [DEBU] {9898c809364a4c17da79e47f3e6c3b8f} Response: Hello World
+```
+
+## 相关文档

package/skills/goframe-v2/references//345/276/256/346/234/215/345/212/241/345/274/200/345/217/221//346/213/246/346/210/252/345/231/250/347/273/204/344/273/266.md

@@ -0,0 +1,45 @@
+`gRPC` 支持拦截器（Interceptor）特性，允许开发者在 RPC 调用前后添加自定义逻辑，从而提高了 `gRPC` 的灵活性和可扩展性。拦截器类似于 `HTTP` 服务中的中间件，可用于实现日志记录、认证验证、性能监控、错误处理等通用功能。
+
+## 拦截器使用
+
+### 服务端
+
+使用 `grpcx.Server.ChainUnary` 方法为服务端添加额外的一元拦截器（Unary Interceptor）。拦截器将按照添加顺序依次执行，形成拦截器链：
+
+```go
+c := grpcx.Server.NewConfig()
+c.Options = append(c.Options, []grpc.ServerOption{
+    grpcx.Server.ChainUnary(
+        grpcx.Server.UnaryValidate,
+    )}...,
+)
+s := grpcx.Server.New(c)
+user.Register(s)
+s.Run()
+```
+
+### 客户端
+
+使用 `grpcx.Client.ChainUnary` 方法为客户端添加额外的一元拦截器。客户端拦截器可以在发送请求前后执行自定义逻辑：
+
+```go
+conn = grpcx.Client.MustNewGrpcClientConn("demo", grpcx.Client.ChainUnary(
+    grpcx.Client.UnaryTracing,
+))
+```
+
+## 拦截器列表
+
+框架的 `grpcx` 组件提供了一系列常用的拦截器，部分为内置默认启用，部分可选择性引入使用。
+
+| 拦截器 | 使用位置 | 是否内置 | 功能描述 |
+| --- | --- | --- | --- |
+| `UnaryError` | 客户端 | 是 | 集成框架错误处理组件，用于统一错误处理。 |
+| `UnaryTracing` | 客户端 | 是 | 支持分布式链路跟踪，自动传播 TraceID。 |
+| `StreamTracing` | 客户端 | 是 | 支持流式 RPC 的链路跟踪（长连接）。 |
+| `UnaryError` | 服务端 | 是 | 集成框架错误处理组件，用于统一错误处理。 |
+| `UnaryRecover` | 服务端 | 是 | 自动捕获服务端处理过程中的 `panic`，防止服务崩溃。 |
+| `UnaryAllowNilRes` | 服务端 | 是 | 允许返回 `nil` 的响应对象，提高灵活性。 |
+| `UnaryValidate` | 服务端 | 否 | 基于结构体标签的自动数据校验，需要手动引入。 |
+| `UnaryTracing` | 服务端 | 是 | 支持分布式链路跟踪，自动接收和传播 TraceID。 |
+| `StreamTracing` | 服务端 | 是 | 支持流式 RPC 的链路跟踪（长连接）。 |