docs(kitex): document disabled RPCInfo pooling by default

content/en/docs/kitex/Best Practice/self_check/panic_self_check.md

@@ -341,7 +341,7 @@ Common scenarios include:
 
 ### Asynchronous Use of RPCInfo
 
-Panic occurs when attempting to access data such as `RPCInfo` outside of the `handler` method by passing the `context` parameter of the `handler`.
+Panic occurs when attempting to access data such as `RPCInfo` outside of the `handler` method by passing the `context` parameter of the `handler`. For correct usage, see [Asynchronous usage](/docs/kitex/tutorials/basic-feature/acquire_rpcinfo/#12-asynchronous-usage).
 
 ## Known Panics Resolved by Upgrading the Framework Version
 

content/en/docs/kitex/Best Practice/usage_attention.md

@@ -2,16 +2,18 @@
 title: "Usage Attention"
 linkTitle: "Usage Attention"
 weight: 1
-date: 2024-02-18
+date: 2026-07-01
 keywords: ["Kitex", "RPCInfo", "client", "Set", "Map"]
 description: "This doc describes usage attentions in Kitex RPCInfo, client creation, and mass data transfer scenarios."
 ---
 
 ## Do not use RPCInfo asynchronously
 
-By default, the lifecycle of Kitex's RPCInfo is from the start of the request until the response is returned (for performance reasons). Afterward, it is put into a `sync.Pool` for reuse. In the server-side, if RPCInfo is asynchronously accessed and used within the business handler, it may read dirty data or encounter a null pointer and panic.
+When RPCInfo pooling and reuse is enabled, Kitex's RPCInfo lifecycle is from the start of the request until the response is returned for performance reasons. Afterward, it is put into `sync.Pool` for reuse. On the server side, if RPCInfo is asynchronously accessed and used within the business handler, dirty data or nil pointer panic may occur.
 
-If there is indeed a scenario where asynchronous usage is required, there are two approaches:
+For safety, Kitex (>= v0.16.3) disables RPCInfo pooling and reuse by default. After a request finishes, the framework does not reset RPCInfo and put it back into the pool by default.
+
+If asynchronous usage is required, there are two approaches:
 
 - Use `rpcinfo.FreezeRPCInfo` provided by Kitex to make a copy of the initial RPCInfo before using it.
 

content/en/docs/kitex/Tutorials/basic-feature/acquire_rpcinfo.md

@@ -1,14 +1,34 @@
 ---
 title: "Acquire Kitex RPC Info "
-date: 2023-11-29
+date: 2026-07-01
 weight: 8
 keywords: ["Acquire Kitex RPC Info "]
 description: ""
 ---
 
+> ⚠️ Note: RPCInfo pooling and reuse will be gradually removed in the versions after [v0.16.2](https://github.com/cloudwego/kitex/releases/tag/v0.16.2), in order to reduce the mental burden on users during development.
+
 ## Acquire RPC information
 
-The default lifecycle of Kitex's RPCInfo is from the start of the request to the return of the request (performance considerations), and then it will be placed in sync.Pool to reuse. On the Server side, if it is asynchronously obtained and used in the business Handler, it may lead to read dirty data, nil panic.
+When RPCInfo pooling and reuse is enabled, Kitex's RPCInfo lifecycle is from the start of the request to the return of the request for performance reasons. After that, it is put into `sync.Pool` for reuse. On the server side, if RPCInfo is asynchronously obtained and used in a business handler, dirty data or nil pointer panic may occur.
+
+For safety, Kitex disables RPCInfo pooling and reuse by default. After a request finishes, the framework does not reset RPCInfo and put it back into the pool by default. Therefore, when business code reads a captured `ctx` asynchronously after the request returns, it will not panic due to the framework reusing the object and clearing its fields.
+
+### RPCInfo Pooling Switch
+
+RPCInfo pooling is disabled by default. To explicitly enable reuse, set the following environment variable:
+
+```bash
+KITEX_ENABLE_RPCINFO_POOL=1
+```
+
+The legacy disable switch is still kept for compatibility:
+
+```bash
+KITEX_DISABLE_RPCINFO_POOL=1
+```
+
+Priority: `KITEX_ENABLE_RPCINFO_POOL` > `KITEX_DISABLE_RPCINFO_POOL`
 
 **Note:** Some information needs to rely on the transport protocol (TTHeader or HTTP2) and corresponding MetaHandler. Please refer to [here](/docs/kitex/tutorials/basic-feature/protocol/transport_protocol/#thrift).
 
@@ -26,7 +46,9 @@ The default lifecycle of Kitex's RPCInfo is from the start of the request to the
 
 ### 1.2 Asynchronous usage
 
-If you need to get RPCInfo in the new goroutine, there are two ways to use it. Choose one and get the specific information as above.
+> If the framework version is earlier than v0.16.2 and the environment variable `KITEX_DISABLE_RPCINFO_POOL=true` is not explicitly set
+
+If you need to get RPCInfo in a new goroutine, there are two ways to use it. Choose one and get the specific information as above.
 
 - **Method 1:** Use the rpcinfo.FreezeRPCInfo provided by Kitex to copy the initial RPCInfo and then use it.
   However, there is additional consumption due to deep copying of rpcinfo.
@@ -49,8 +71,7 @@ go func(ctx context.Context) {
 
 ```
 
-- **Method 2 [Kitex v0.8.0+]:** Disable RPCInfo pool
-  Set environment variables _KITEX_DISABLE_RPCINFO_POOL=true_ or configure _rpcinfo.EnablePool(false)_ in the code.
+- **Method 2 [Kitex v0.8.0+]:** Disable RPCInfo recycling. You can either set the environment variable `KITEX_DISABLE_RPCINFO_POOL=true`, or configure `rpcinfo.EnablePool(false)` in code.
 
 ## Meta Info Transparent Transmission
 

content/en/docs/kitex/Tutorials/framework-exten/middleware.md

@@ -124,7 +124,7 @@ The provided example is for illustrative purposes, and it is indeed important to
 
 ### Precautions
 
-1. If RPCInfo is used in custom middleware, be aware that RPCInfo will be recycled after the rpc ends, so if you use goroutine operation RPCInfo in middleware, there will be issues . Please avoid such operations .
+1. [Kitex <= v0.16.2] If RPCInfo is used in custom middleware, be aware that RPCInfo will be recycled after the rpc ends. If you operate RPCInfo in a goroutine in middleware, issues may occur. Please avoid such operations. For details, see [Asynchronous usage](/docs/kitex/tutorials/basic-feature/acquire_rpcinfo/#12-asynchronous-usage).
 2. Middleware is a chained call, if you use `result. SetSuccess()` or some other way to modify the response in any middleware, the upstream middlewares will receive the modified response.
 
 ### gRPC Middleware

content/zh/docs/kitex/Best Practice/self_check/panic_self_check.md

@@ -2,7 +2,7 @@
 title: "Panic 自查手册"
 linkTitle: "Panic 自查手册"
 weight: 1
-date: 2024-02-18
+date: 2026-07-01
 description: "发生 Panic 时如何快速排查"
 
 ---
@@ -343,7 +343,7 @@ Map 并发操作属于不可挽回的错误，因此系统会直接 crash，无
 
 ### 异步使用 RPCInfo
 
-将 `handler` 方法的 `context` 参数传递到 `handler` 外使用并尝试获取诸如 `RPCInfo` 这样的数据导致 panic。
+将 `handler` 方法的 `context` 参数传递到 `handler` 外使用并尝试获取诸如 `RPCInfo` 这样的数据导致 panic。正确使用方式见 [异步使用方式](/zh/docs/kitex/tutorials/basic-feature/acquire_rpcinfo/#12-异步使用方式)。
 
 ## 已知升级框架版本可解决的 Panic
 

content/zh/docs/kitex/Best Practice/usage_attention.md

@@ -2,14 +2,16 @@
 title: "使用注意事项"
 linkTitle: "使用注意事项"
 weight: 1
-date: 2024-02-18
+date: 2026-07-01
 keywords: ["Kitex", "RPCInfo", "client", "Set", "Map"]
 description: "介绍 Kitex RPCInfo、client 创建、大量数据传输场景下的注意事项。"
 ---
 
 ## 勿异步使用 RPCInfo
 
-Kitex 的 RPCInfo 的生命周期默认是从请求开始到请求返回（性能考虑），随后会被放到 `sync.Pool` 中复用，在 Server 端，如果在业务 Handler 中异步获取使用，可能会读到脏数据 / 空指针而 panic。
+当开启 RPCInfo 池化复用功能时，Kitex 的 RPCInfo 的生命周期默认是从请求开始到请求返回（性能考虑），随后会被放到 `sync.Pool` 中复用，在 Server 端，如果在业务 Handler 中异步获取使用，可能会读到脏数据 / 空指针而 panic。
+
+出于安全性考虑，Kitex (>= v0.16.3) 默认关闭 RPCInfo 池化复用。请求结束后，框架不会默认将 RPCInfo 重置并放回池中。
 
 如果的确存在异步使用的场景，有两种方式：
 

content/zh/docs/kitex/Tutorials/basic-feature/acquire_rpcinfo.md

@@ -1,14 +1,34 @@
 ---
 title: "框架 RPC 信息的获取"
-date: 2023-11-29
+date: 2026-07-01
 weight: 8
 keywords: ["框架 RPC 信息的获取"]
 description: ""
 ---
 
+> ⚠️ 注意：RPCInfo 将在 [v0.16.2](https://github.com/cloudwego/kitex/releases/tag/v0.16.2) 的后续几个版本逐步删除池化复用，以便于降低用户开发时的心智负担。
+
 ## 从 RPCInfo 获取 RPC 信息
 
-Kitex 的 RPCInfo 的生命周期默认是从请求开始到请求返回（性能考虑），随后会被放到 sync.Pool 中复用。在 Server 端，如果在业务 Handler 中异步获取使用，可能会读到脏数据 / 空指针而 panic。
+当开启 RPCInfo 池化复用功能时，Kitex 的 RPCInfo 的生命周期默认是从请求开始到请求返回（性能考虑），随后会被放到 sync.Pool 中复用。在 Server 端，如果在业务 Handler 中异步获取使用，可能会读到脏数据 / 空指针而 panic。
+
+出于安全性考虑，Kitex 默认关闭 RPCInfo 池化复用。请求结束后，框架不会默认将 RPCInfo 重置并放回池中，因此业务在请求结束后异步读取已捕获的 `ctx` 时，不会因为框架复用该对象而读到空字段并 panic。
+
+### RPCInfo 池化开关
+
+RPCInfo 池化复用默认关闭。需要显式开启复用时，可以设置环境变量：
+
+```bash
+KITEX_ENABLE_RPCINFO_POOL=1
+```
+
+兼容旧版本的关闭开关仍然保留：
+
+```bash
+KITEX_DISABLE_RPCINFO_POOL=1
+```
+
+优先级：`KITEX_ENABLE_RPCINFO_POOL` > `KITEX_DISABLE_RPCINFO_POOL`
 
 **注意：** 部分信息需要依赖传输协议（TTHeader 或 HTTP2）和对应的 Metahandler，如果是 Thrift 配置方式见 [这里](/zh/docs/kitex/tutorials/basic-feature/protocol/transport_protocol/#thrift)。
 
@@ -28,6 +48,8 @@ Kitex 的 RPCInfo 的生命周期默认是从请求开始到请求返回（性
 
 ### 1.2 异步使用方式
 
+> 如果框架版本小于 v0.16.2，并没有显式设置环境变量 `KITEX_DISABLE_RPCINFO_POOL=true`
+
 如果需要在新的 Goroutine 里获取 RPCInfo，有两种使用方式，选择其中一种，获取具体信息与上面一样。
 
 - **方式一：** 用 Kitex 提供的 rpcinfo.FreezeRPCInfo 复制初始的 RPCInfo 再使用

content/zh/docs/kitex/Tutorials/framework-exten/middleware.md

@@ -1,6 +1,6 @@
 ---
 title: "Middleware 扩展"
-date: 2021-08-26
+date: 2026-07-01
 weight: 1
 description: >
 ---
@@ -125,7 +125,7 @@ func ExampleMiddleware(next endpoint.Endpoint) endpoint.Endpoint {
 
 ### 注意事项
 
-1. 如果自定义 middleware 中用到了 RPCInfo，注意 RPCInfo 在 rpc 结束之后会被回收。如果在 middleware 中开启 goroutine 操作 RPCInfo 有可能会出现问题，请避免这类操作。
+1. [Kitex <= v0.16.2] 如果自定义 middleware 中用到了 RPCInfo，注意 RPCInfo 在 rpc 结束之后会被回收。如果在 middleware 中开启 goroutine 操作 RPCInfo 有可能会出现问题，请避免这类操作，详情见 [异步使用方式](/zh/docs/kitex/tutorials/basic-feature/acquire_rpcinfo/#12-异步使用方式)。
 2. Middleware 为链式调用，若在任一 middleware 中使用 `result.SetSuccess()` 或其他方式修改了 response，上游 middleware 会接收到修改后的 response。
 
 ### gRPC 中间件