Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs compnent metadata #147

Merged
merged 2 commits into from
Jul 18, 2022
Merged

Update docs compnent metadata #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0c8a1b0
修改元数据章节文档，包含中英文版本
Terrygmx Jul 10, 2022
55dbae7
修改不正确的链接
Terrygmx Jul 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/component/06-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ keywords:
- HTTP
---

微服务之间将会通过 HTTP 和 gRPC 进行接口交互，所以服务架构需要统一 Metadata 传递使用。
目前 gRPC 中也可以携带 Metadata 传递，原理是放到 HTTP Header 中，然后上游将会收到对应的 Metadata 信息。
所以设计上，也是通过 HTTP Header 进行传递，在框架中先通过 metadata 包封装成key/value结构，然后携带到 Transport Header 中。
微服务之间通过 HTTP 和 gRPC API 进行接口交互，服务架构需要使用统一的元信息（Metadata）传输进行微服务间的传递。
目前 gRPC 中可以携带元信息传递，原理是将元信息放入 HTTP Header 中，这样上游即可收到对应的元信息 信息。
因此在Kratos的设计上，也是通过 HTTP Header 进行传递。在框架中先将元信息包封装成key/value结构，然后携带到 Transport Header 中。

### 默认格式规范

Expand All @@ -24,15 +24,15 @@ keywords:
也可以在 middleware/metadata 定制自己的 key prefix，配置固定的元信息传递

### 使用方式
首先配置 client/server 对应的 middleware/metadata 插件，然后可以自定义传递 key prefix，或者 metadata 常量，例如 caller。
最后可以通过 metadata 包中的 `NewClientContext` 或者 `FromServerContext` 进行配置或者获取。
首先配置 client/server 对应的 middleware/metadata 插件，然后可以自定义传递 key prefix，或者元信息常量，例如 caller。
然后可以通过元信息包中的 `NewClientContext` 或者 `FromServerContext` 进行配置或者获取。


#### 注册 metadata 中间件
#### 注册元信息中间件
```go
// https://github.com/go-kratos/examples/tree/main/metadata

// 注册 metadata 中间件到 gRPC 或 HTTP 的 server 或 client 中
// 注册元信息中间件到 gRPC 或 HTTP 的 server 或 client 中

// server
grpcSrv := grpc.NewServer(
Expand All @@ -57,13 +57,13 @@ conn, err := grpc.DialInsecure(
),
)
```
#### 获取 metadata 字段的值
#### 获取元信息字段的值
```go
if md, ok := metadata.FromServerContext(ctx); ok {
extra = md.Get("x-md-global-extra")
}
```
#### 传递 metadata
#### 设置元信息字段的值
```go
ctx = metadata.AppendToClientContext(ctx, "x-md-global-extra", "2233")
```
14 changes: 8 additions & 6 deletions i18n/en/docusaurus-plugin-content-docs/current/component/06-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,20 +12,22 @@ keywords:
- HTTP
---

Microservices interact through HTTP and gRPC API, so the service architecture needs to be used for uniform Metadata transport.
Currently, you could also carry a Metadata pass in gRPC, The metadata will be put into HTTP Header, and then upstream will receive the corresponding Metadata Information.
So it's also designed to be delivered via HTTP Header, first wrapped in a key/value structure in a framework through a metadata package, and then carried to Transport Header.
Microservices interact with each other via HTTP and gRPC API, so the service architecture should use unified Metadata transmission.
At present, It is possible for gRPC to carry Metadata, by putting Metadata in HTTP Header, so the upstream can receive the corresponding Metadata information.
Therefore, in Kratos, it is also carried by HTTP Header. In the framework, it is packaged in key/value structure, and carried in Transport Header.

### Default Metadata Convention

- x-md-global-xxx，will be transported globally, e.g. mirror/color/criticality
- x-md-local-xxx，will be transported locally, e.g. caller

You could also set your custom key prefix in middleware/metadata for constant metadata.
It is also possible to customize the key prefix in middleware/metadata for constant metadata.

### Usage
First, the middleware/metadata plug-in should be configured to client/server, and then you can customize the transport key prefix, or the metadata constant, such as caller.
Finally, it can be configured or obtained through `NewClientContext` or `FromServerContext` in the metadata package.
First, you need to configure corresponding middleware/metadata plug-ins for the client/server.
Then you can customize the key prefix or metadata constant, e.g. caller.
Finally you can use `NewClientContext` or `FromServerContext` from Metadata package to configure or get the metadata.


#### Configuration
```go
Expand Down