docs: clarify HTTP routes and client examples

docs/user_guide/client/connection_mode.zh_CN.md

@@ -90,13 +90,14 @@ import "trpc.group/trpc-go/trpc-go/pool/connpool"
 /*
 连接池参数
 type Options struct {
-	MinIdle             int			  	// 最小空闲连接数量，由连接池后台周期性补充，0 代表不做补充
-	MaxIdle             int           	// 最大空闲连接数量，0 代表不做限制，框架默认值 65535
-	MaxActive           int           	// 用户可用连接的最大并发数，0 代表不做限制
+	MinIdle             int           	// 最小空闲连接数量，由连接池后台周期性补充，0 代表不做补充，默认值 0
+	MaxIdle             int           	// 最大空闲连接数量，0 代表不做限制，框架默认值 65536
+	MaxActive           int           	// 用户可用连接的最大并发数，0 代表不做限制，默认值 0
 	Wait                bool          	// 可用连接达到最大并发数时，是否等待，默认为 false, 不等待
 	IdleTimeout         time.Duration 	// 空闲连接超时时间，0 代表不做限制，框架默认值 50s
-	MaxConnLifetime     time.Duration 	// 连接的最大生命周期，0 代表不做限制
+	MaxConnLifetime     time.Duration 	// 连接的最大生命周期，0 代表不做限制，默认值 0
 	DialTimeout         time.Duration 	// 建立连接超时时间，框架默认值 200ms
+	PoolIdleTimeout     time.Duration 	// 连接池空闲超时时间，0 代表不做限制，框架默认值 100s
 	ForceClose          bool          	// 用户使用连接后是否强制关闭，默认为 false, 放回连接池
 	PushIdleConnToTail  bool			// 放回连接池时的方式，默认为 false, 采用 LIFO 获取空闲连接
 }
@@ -126,6 +127,12 @@ if err != nil {
 log.Info("req:%v, rsp:%v, err:%v", req, rsp, err)
 ```
 
+**注意：** 虽然示例中只创建了一个 `pool` 实例并传入，但 tRPC-Go 内部会为每个不同的下游 IP 地址（`network+address+protocol` 组合）创建独立的 `ConnectionPool` 实例。这些 `ConnectionPool` 实例共享相同的配置参数（如 `MaxIdle`、`MinIdle`、`IdleTimeout` 等），但各自管理自己的连接。这意味着：
+
+- 每个下游 IP 都有自己独立的连接池实例
+- 所有连接池实例使用相同的配置参数
+- 连接池实例之间互不影响，各自维护自己的连接
+
 #### 设置空闲连接超时
 
 在客户端的连接池模式中，框架默认会设置一个 50 秒的空闲超时时间。

docs/user_guide/client/overview.md

@@ -91,7 +91,7 @@ func (s *greeterServerImpl) SayHello(ctx context.Context, req *pb.HelloRequest)
         log.ErrorContextf(ctx, "say hi fail:%v", err)
         return nil, errs.New(10000, "xxxxx") 
     }
-    return &pb.HelloReply{Xxx: reply.Xxx} nil
+    return &pb.HelloReply{Xxx: reply.Xxx}, nil
 }
 
 func main(){
@@ -119,7 +119,7 @@ import (
 )
 
 // Generally, small tools start from the main function
-func main {
+func main() {
     // Since there is no configuration file to help initialize the plugin, you need to manually initialize the North Star
     pselector.RegisterDefault()
     // Create a client call proxy

docs/user_guide/client/overview.zh_CN.md

@@ -94,7 +94,7 @@ func (s *greeterServerImpl) SayHello(ctx context.Context, req *pb.HelloRequest)
         log.ErrorContextf(ctx, "say hi fail:%v", err)
         return nil, errs.New(10000, "xxxxx") 
     }
-    return &pb.HelloReply{Xxx: reply.Xxx} nil
+    return &pb.HelloReply{Xxx: reply.Xxx}, nil
 }
 
 func main(){
@@ -122,7 +122,7 @@ import (
 )
 
 // 一般小工具都是从 main 函数写起
-func main {
+func main() {
     // 由于没有配置文件帮忙初始化插件，所以需要自己手动初始化北极星
     pselector.RegisterDefault()
     // 创建一个客户端调用代理

http/README.md

@@ -144,6 +144,16 @@ func handle(w http.ResponseWriter, r *http.Request) error {
 }
 ```
 
+**Notes**
+
+- **Exact match**: In URL registration mode, `pattern` is treated as an exact
+  `URL.Path` match. Patterns like `/api/callback/*` do **not** work as prefix
+  matching.
+- **Wildcard**: Only `"*"` is treated as a wildcard handler, and it works as a
+  fallback when no exact match exists.
+- **Need routing features** (prefix match, path params, regex): use
+  `RegisterNoProtocolServiceMux` and register routes in your mux/router.
+
 ### Client
 
 This refers to calling a standard HTTP service, which is not necessarily built on the tRPC-Go framework downstream
@@ -172,7 +182,6 @@ package main
 import (
     "context"
 
-    trpc "trpc.group/trpc-go/trpc-go"
     "trpc.group/trpc-go/trpc-go/client"
     "trpc.group/trpc-go/trpc-go/codec"
     "trpc.group/trpc-go/trpc-go/http"

http/README.zh_CN.md

@@ -144,6 +144,15 @@ func handle(w http.ResponseWriter, r *http.Request) error {
 }
 ```
 
+**注意事项**
+
+- **精确匹配**：URL 注册模式下，`pattern` 会被当作 `URL.Path` 的精确匹配。
+  例如 `/api/callback/*` 不会按前缀匹配 `/api/callback/xxx`。
+- **通配兜底**：只有 `"*"` 会作为兜底 handler，在没有任何精确匹配命中时才会
+  生效。
+- **需要路由能力**（前缀匹配、路径参数、正则等）：请使用
+  `RegisterNoProtocolServiceMux`，在 mux/router 里注册路由。
+
 ### 客户端
 
 这里指的是调用一个标准 HTTP 服务, 下游这个标准 HTTP 服务并不一定是基于 tRPC-Go 框架构建的
@@ -172,10 +181,9 @@ package main
 import (
     "context"
 
-    trpc "trpc.group/trpc-go/trpc-go"
     "trpc.group/trpc-go/trpc-go/client"
     "trpc.group/trpc-go/trpc-go/codec"
-  trpc "trpc.group/trpc-go/trpc-go"
+    "trpc.group/trpc-go/trpc-go/http"
     "trpc.group/trpc-go/trpc-go/log"
 )
 

restful/restful_test.go

@@ -21,6 +21,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"strings"
 	"testing"
@@ -701,8 +702,12 @@ func TestBasedOnFastHTTP(t *testing.T) {
 		thttp.NewRESTServerTransport(true))
 
 	// service registration
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	require.Nil(t, err)
+	endpoint := "http://" + listener.Addr().String()
+
 	s := &server.Server{}
-	service := server.New(server.WithAddress("127.0.0.1:45678"),
+	service := server.New(server.WithListener(listener),
 		server.WithServiceName("trpc.test.helloworld.FastHTTP"),
 		server.WithProtocol("restful_based_on_fasthttp"),
 		server.WithRESTOptions(
@@ -747,9 +752,18 @@ func TestBasedOnFastHTTP(t *testing.T) {
 	hpb.RegisterGreeterService(s, &greeterServerImpl{})
 
 	// start server
+	serveErr := make(chan error, 1)
 	go func() {
-		err := s.Serve()
-		require.Nil(t, err)
+		serveErr <- s.Serve()
+	}()
+	defer func() {
+		require.Nil(t, s.Close(nil))
+		select {
+		case err := <-serveErr:
+			require.Nil(t, err)
+		case <-time.After(time.Second):
+			t.Fatal("timeout waiting for server close")
+		}
 	}()
 
 	time.Sleep(100 * time.Millisecond)
@@ -758,10 +772,10 @@ func TestBasedOnFastHTTP(t *testing.T) {
 	data := `{"name": "xyz"}`
 	buf := bytes.Buffer{}
 	gBuf := gzip.NewWriter(&buf)
-	_, err := gBuf.Write([]byte(data))
+	_, err = gBuf.Write([]byte(data))
 	require.Nil(t, err)
 	gBuf.Close()
-	req, err := http.NewRequest("POST", "http://127.0.0.1:45678/v1/foobar", &buf)
+	req, err := http.NewRequest("POST", endpoint+"/v1/foobar", &buf)
 	require.Nil(t, err)
 	req.Header.Add("Content-Type", "anything")
 	req.Header.Add("Content-Encoding", "gzip")
@@ -785,7 +799,7 @@ func TestBasedOnFastHTTP(t *testing.T) {
 	require.Equal(t, respBody.Message, "test")
 
 	// test matching all by query params
-	req2, err := http.NewRequest("GET", "http://127.0.0.1:45678/v2/bar?name=xyz", nil)
+	req2, err := http.NewRequest("GET", endpoint+"/v2/bar?name=xyz", nil)
 	require.Nil(t, err)
 	resp2, err := http.DefaultClient.Do(req2)
 	require.Nil(t, err)
@@ -796,7 +810,7 @@ func TestBasedOnFastHTTP(t *testing.T) {
 	require.Equal(t, resp2.Header.Get("Content-Type"), "application/json")
 
 	// test server error
-	req3, err := http.NewRequest("GET", "http://127.0.0.1:45678/v2/bar?name=anything", nil)
+	req3, err := http.NewRequest("GET", endpoint+"/v2/bar?name=anything", nil)
 	require.Nil(t, err)
 	resp3, err := http.DefaultClient.Do(req3)
 	require.Nil(t, err)
@@ -810,7 +824,7 @@ func TestBasedOnFastHTTP(t *testing.T) {
 	_, err = gBuf4.Write([]byte(data4))
 	require.Nil(t, err)
 	gBuf4.Close()
-	req4, err := http.NewRequest("POST", "http://127.0.0.1:45678/v1/foobar", &buf4)
+	req4, err := http.NewRequest("POST", endpoint+"/v1/foobar", &buf4)
 	require.Nil(t, err)
 	req4.Header.Add("Content-Type", "anything")
 	req4.Header.Add("Content-Encoding", "gzip")