### Enable Connection Pool Warm-up with `client.WithWarmingUp`

Source: https://context7.com/cloudwego/kitex/llms.txt

Pre-establishes connections during client initialization to avoid connection setup latency on the first requests. Configure target addresses and the number of connections per target.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/warmup"
)

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("10.0.0.1:8888"),
    client.WithWarmingUp(&warmup.ClientOption{
        PoolOption: &warmup.PoolOption{
            Targets: map[string][]string{
                "tcp": {"10.0.0.1:8888"},
            },
            ConnNum: 5, // pre-create 5 connections per target
        },
        ErrorHandling: warmup.WarningLog,
    }),
)
```

--------------------------------

### Implement Custom Service Registry with `registry.Registry`

Source: https://context7.com/cloudwego/kitex/llms.txt

Implement the `Register` and `Deregister` methods to integrate with any service registry. This example shows a basic structure for a custom registry.

```go
import (
    "github.com/cloudwego/kitex/pkg/registry"
    "github.com/cloudwego/kitex/server"
)

type MyRegistry struct{}

func (r *MyRegistry) Register(info *registry.Info) error {
    log.Printf("registering %s at %s", info.ServiceName, info.Addr)
    // write to your registry backend
    return nil
}

func (r *MyRegistry) Deregister(info *registry.Info) error {
    log.Printf("deregistering %s", info.ServiceName)
    return nil
}

svr := echo.NewServer(&EchoHandler{
},
    server.WithServiceAddr(addr),
    server.WithRegistry(&MyRegistry{}),
)
```

--------------------------------

### Configure Structured Logging with `klog`

Source: https://context7.com/cloudwego/kitex/llms.txt

Replace the default logger by calling `klog.SetLogger`. Use module-level helpers for logging. Set the log level globally before starting servers/clients.

```go
import (
    "github.com/cloudwego/kitex/pkg/klog"
    // e.g. zerolog adapter from kitex-contrib
)

// Set a custom logger globally before starting servers/clients:
klog.SetLogger(myZerologAdapter)
klog.SetLevel(klog.LevelWarn)

// Use anywhere in middleware or handlers:
klog.Infof("handling request for method=%s", method)
klog.CtxInfof(ctx, "request id=%s", requestID)
```

--------------------------------

### Attach Tracer with `client.WithTracer`

Source: https://context7.com/cloudwego/kitex/llms.txt

Adds a `stats.Tracer` that receives `Start` and `Finish` events for each RPC call. Integrate with OpenTelemetry, Jaeger, Zipkin, or custom systems via the `kitex-contrib` adapters.

```go
import (
    "github.com/cloudwego/kitex/client"
    oteltrace "github.com/kitex-contrib/obs-opentelemetry/tracing"
)

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("127.0.0.1:8888"),
    client.WithSuite(oteltrace.NewClientSuite()),
)
```

--------------------------------

### Register Server Lifecycle Hooks

Source: https://context7.com/cloudwego/kitex/llms.txt

Registers callbacks that run after the server starts or before it shuts down. Useful for initialising background workers or flushing metrics.

```go
import "github.com/cloudwego/kitex/server"

func init() {
    server.RegisterStartHook(func() {
        log.Println("server started, warming up caches…")
        initializeCache()
    })
    server.RegisterShutdownHook(func() {
        log.Println("server shutting down, flushing metrics…")
        metrics.Flush()
    })
}
```

--------------------------------

### server.RegisterStartHook / server.RegisterShutdownHook

Source: https://context7.com/cloudwego/kitex/llms.txt

Registers callbacks that execute after the server has started or just before it shuts down, useful for initializing background tasks or flushing metrics.

```APIDOC
## server.RegisterStartHook / server.RegisterShutdownHook — Lifecycle hooks

Registers callbacks that run after the server starts or before it shuts down. Useful for initialising background workers or flushing metrics.

```go
import "github.com/cloudwego/kitex/server"

func init() {
    server.RegisterStartHook(func() {
        log.Println("server started, warming up caches…")
        initializeCache()
    })
    server.RegisterShutdownHook(func() {
        log.Println("server shutting down, flushing metrics…")
        metrics.Flush()
    })
}
```
```

--------------------------------

### Create Kitex RPC Server

Source: https://context7.com/cloudwego/kitex/llms.txt

Use `server.NewServer` to create an RPC server. Configure listen address, middleware, registry, limits, and transport settings via options.

```go
package main

import (
    "net"
    "log"

    "github.com/cloudwego/kitex/server"
    "github.com/cloudwego/kitex/pkg/limit"
    // generated by kitex tool:
    echo "github.com/example/kitex_gen/echo/echoservice"
)

type EchoHandler struct{}

func (h *EchoHandler) Echo(ctx context.Context, req *echo.Request) (*echo.Response, error) {
    return &echo.Response{Message: "Hello " + req.Name}, nil
}

func main() {
    addr, _ := net.ResolveTCPAddr("tcp", ":8888")
    svr := echo.NewServer(
        &EchoHandler{},
        server.WithServiceAddr(addr),
        server.WithExitWaitTime(5*time.Second),
        server.WithLimit(&limit.Option{MaxConnections: 10000, MaxQPS: 5000}),
        server.WithMiddleware(func(next endpoint.Endpoint) endpoint.Endpoint {
            return func(ctx context.Context, req, resp interface{}) error {
                log.Printf("incoming request")
                return next(ctx, req, resp)
            }
        }),
    )
    if err := svr.Run(); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Configure Server with Service Registration

Source: https://context7.com/cloudwego/kitex/llms.txt

Registers the server with a service registry on startup and deregisters on shutdown. Accepts any type implementing `registry.Registry`.

```go
import (
    "github.com/cloudwego/kitex/server"
    etcd "github.com/kitex-contrib/registry-etcd"
)

r, err := etcd.NewEtcdRegistry([]string{"127.0.0.1:2379"})
if err != nil {
    log.Fatal(err)
}

svr := echo.NewServer(&EchoHandler{},
    server.WithServiceAddr(addr),
    server.WithRegistry(r),
)
```

--------------------------------

### Create Kitex RPC Client

Source: https://context7.com/cloudwego/kitex/llms.txt

Use `client.NewClient` to create a low-level RPC client. Configure host ports, timeouts, and connection pooling via options.

```go
package main

import (
    "context"
    "log"
    "time"

    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/connpool"
    echo "github.com/example/kitex_gen/echo/echoservice"
)

func main() {
    cli, err := echo.NewClient(
        "echo-service",
        client.WithHostPorts("127.0.0.1:8888"),
        client.WithRPCTimeout(3*time.Second),
        client.WithConnectTimeout(500*time.Millisecond),
        client.WithLongConnection(connpool.IdleConfig{
            MinIdlePerAddress: 0,
            MaxIdlePerAddress: 10,
            MaxIdleGlobal:     1000,
            MaxIdleTimeout:    30 * time.Second,
        }),
    )
    if err != nil {
        log.Fatal(err)
    }
    resp, err := cli.Echo(context.Background(), &echo.Request{Name: "world"})
    if err != nil {
        log.Printf("rpc error: %v", err)
        return
    }
    log.Println(resp.Message) // "Hello world"
}
```

--------------------------------

### Connection Pool Warm-up

Source: https://context7.com/cloudwego/kitex/llms.txt

Use `client.WithWarmingUp` to pre-establish connections during client initialization, reducing latency for the first requests. Configure targets and connection numbers.

```APIDOC
## `client.WithWarmingUp` — Connection pool warm-up

Pre-establishes connections during client initialization so the first real requests do not incur connection setup latency.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/warmup"
)

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("10.0.0.1:8888"),
    client.WithWarmingUp(&warmup.ClientOption{
        PoolOption: &warmup.PoolOption{
            Targets: map[string][]string{
                "tcp": {"10.0.0.1:8888"},
            },
            ConnNum: 5, // pre-create 5 connections per target
        },
        ErrorHandling: warmup.WarningLog,
    }),
)
```
```

--------------------------------

### Configure Client with Backup Request Policy

Source: https://context7.com/cloudwego/kitex/llms.txt

Sends a second request after a configurable delay if the first has not yet returned. Accepts the first response that arrives.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/retry"
)

bp := retry.NewBackupPolicy(50 /* delay ms */)
bp.WithMaxRetryTimes(1)

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("127.0.0.1:8888"),
    client.WithBackupRequest(bp),
)
```

--------------------------------

### Implement custom service discovery with Resolver interface

Source: https://context7.com/cloudwego/kitex/llms.txt

Implement the `discovery.Resolver` interface to integrate any service registry. The framework caches results and uses `Diff` for load balancer updates.

```go
import (
    "context"

    "github.com/cloudwego/kitex/pkg/discovery"
    "github.com/cloudwego/kitex/pkg/rpcinfo"
)

type MyResolver struct{}

func (r *MyResolver) Target(ctx context.Context, target rpcinfo.EndpointInfo) string {
    return target.ServiceName()
}

func (r *MyResolver) Resolve(ctx context.Context, desc string) (discovery.Result, error) {
    instances := []discovery.Instance{
        discovery.NewInstance("tcp", "10.0.0.1:8888", 10, nil),
        discovery.NewInstance("tcp", "10.0.0.2:8888", 10, nil),
    }
    return discovery.Result{Cacheable: true, CacheKey: desc, Instances: instances}, nil
}

func (r *MyResolver) Diff(key string, prev, next discovery.Result) (discovery.Change, bool) {
    return discovery.DefaultDiff(key, prev, next)
}

func (r *MyResolver) Name() string { return "my-resolver" }

// Usage:
cli, _ := echo.NewClient("echo-service", client.WithResolver(&MyResolver{}))
```

--------------------------------

### server.WithRegistry

Source: https://context7.com/cloudwego/kitex/llms.txt

Registers the server with a service registry upon startup and deregisters upon shutdown. Accepts any type that implements the `registry.Registry` interface.

```APIDOC
## server.WithRegistry — Service registration

Registers the server with a service registry on startup and deregisters on shutdown. Accepts any type implementing `registry.Registry`.

```go
import (
    "github.com/cloudwego/kitex/server"
    etcd "github.com/kitex-contrib/registry-etcd"
)

r, err := etcd.NewEtcdRegistry([]string{"127.0.0.1:2379"})
if err != nil {
    log.Fatal(err)
}

svr := echo.NewServer(&EchoHandler{},
    server.WithServiceAddr(addr),
    server.WithRegistry(r),
)
```
```

--------------------------------

### Configure Server with Middleware

Source: https://context7.com/cloudwego/kitex/llms.txt

Injects a middleware into the server's endpoint chain. Executes for every incoming request before the handler.

```go
import (
    "context"

    "github.com/cloudwego/kitex/server"
    "github.com/cloudwego/kitex/pkg/endpoint"
    "github.com/cloudwego/kitex/pkg/rpcinfo"
)

authMW := func(next endpoint.Endpoint) endpoint.Endpoint {
    return func(ctx context.Context, req, resp interface{}) error {
        ri := rpcinfo.GetRPCInfo(ctx)
        token, _ := ri.From().Tag("token")
        if token != "secret" {
            return errors.New("unauthorized")
        }
        return next(ctx, req, resp)
    }
}

svr := echo.NewServer(&EchoHandler{},
    server.WithServiceAddr(addr),
    server.WithMiddleware(authMW),
)
```

--------------------------------

### server.NewServer

Source: https://context7.com/cloudwego/kitex/llms.txt

Creates a new RPC server instance. It accepts service handlers and various configuration options to customize server behavior, such as listen address, middleware, registry, limits, and transport settings.

```APIDOC
## server.NewServer — Create an RPC server

Creates a `Server` that accepts connections and dispatches them to registered service handlers. Options configure listen address, middleware, registry, limits, and transport settings.

### Usage Example
```go
package main

import (
    "net"
    "log"

    "github.com/cloudwego/kitex/server"
    "github.com/cloudwego/kitex/pkg/limit"
    // generated by kitex tool:
    echo "github.com/example/kitex_gen/echo/echoservice"
)

type EchoHandler struct{}

func (h *EchoHandler) Echo(ctx context.Context, req *echo.Request) (*echo.Response, error) {
    return &echo.Response{Message: "Hello " + req.Name}, nil
}

func main() {
    addr, _ := net.ResolveTCPAddr("tcp", ":8888")
    svr := echo.NewServer(
        &EchoHandler{},
        server.WithServiceAddr(addr),
        server.WithExitWaitTime(5*time.Second),
        server.WithLimit(&limit.Option{MaxConnections: 10000, MaxQPS: 5000}),
        server.WithMiddleware(func(next endpoint.Endpoint) endpoint.Endpoint {
            return func(ctx context.Context, req, resp interface{}) error {
                log.Printf("incoming request")
                return next(ctx, req, resp)
            }
        }),
    )
    if err := svr.Run(); err != nil {
        log.Fatal(err)
    }
}
```
```

--------------------------------

### Configure Client with Middleware

Source: https://context7.com/cloudwego/kitex/llms.txt

Adds a custom `endpoint.Middleware` to the client's invocation chain. Runs for every unary call; useful for logging, tracing, authentication header injection, etc.

```go
import (
    "context"
    "log"
    "time"

    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/endpoint"
)

loggingMW := func(next endpoint.Endpoint) endpoint.Endpoint {
    return func(ctx context.Context, req, resp interface{}) error {
        start := time.Now()
        err := next(ctx, req, resp)
        log.Printf("rpc finished in %v, err=%v", time.Since(start), err)
        return err
    }
}

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("127.0.0.1:8888"),
    client.WithMiddleware(loggingMW),
)
```

--------------------------------

### Kitex Client Custom Service Discovery

Source: https://context7.com/cloudwego/kitex/llms.txt

Integrate a custom service discovery mechanism by providing a `discovery.Resolver` implementation using `client.WithResolver`. The framework will use this resolver for service discovery.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/discovery"
    // e.g. etcd resolver from kitex-contrib:
    etcd "github.com/kitex-contrib/registry-etcd"
)

func main() {
    r, err := etcd.NewEtcdResolver([]string{"127.0.0.1:2379"})
    if err != nil {
        log.Fatal(err)
    }
    cli, err := echo.NewClient("echo-service",
        client.WithResolver(r),
    )
    _ = cli
}
```

--------------------------------

### Configure Client with Custom Load Balancer

Source: https://context7.com/cloudwego/kitex/llms.txt

Replaces the default weighted-round-robin balancer with a custom implementation. Accepts any type implementing `loadbalance.Loadbalancer`.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/loadbalance"
)

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("10.0.0.1:8888", "10.0.0.2:8888"),
    // built-in round-robin:
    client.WithLoadBalancer(loadbalance.NewWeightedRoundRobinBalancer()),
)
```

--------------------------------

### Configure Client with Circuit Breaker

Source: https://context7.com/cloudwego/kitex/llms.txt

Attaches a `circuitbreak.CBSuite` that tracks service-level and instance-level error rates and short-circuits calls when thresholds are exceeded.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/circuitbreak"
    "github.com/cloudwego/kitex/pkg/rpcinfo"
)

cbs := circuitbreak.NewCBSuite(func(ri rpcinfo.RPCInfo) string {
    return ri.To().ServiceName() + "/" + ri.To().Method()
})

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("127.0.0.1:8888"),
    client.WithCircuitBreaker(cbs),
)
```

--------------------------------

### client.NewClient

Source: https://context7.com/cloudwego/kitex/llms.txt

Creates a low-level RPC client. This is the foundation for generated client code and accepts service information and client options to configure connection, timeouts, and pooling.

```APIDOC
## client.NewClient — Create a low-level RPC client

`NewClient` is the foundation used by generated client code. It accepts `*serviceinfo.ServiceInfo` and variadic `client.Option` values, returning a `client.Client` that can invoke arbitrary methods.

### Usage Example
```go
package main

import (
    "context"
    "log"
    "time"

    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/connpool"
    echo "github.com/example/kitex_gen/echo/echoservice"
)

func main() {
    cli, err := echo.NewClient(
        "echo-service",
        client.WithHostPorts("127.0.0.1:8888"),
        client.WithRPCTimeout(3*time.Second),
        client.WithConnectTimeout(500*time.Millisecond),
        client.WithLongConnection(connpool.IdleConfig{
            MinIdlePerAddress: 0,
            MaxIdlePerAddress: 10,
            MaxIdleGlobal:     1000,
            MaxIdleTimeout:    30 * time.Second,
        }),
    )
    if err != nil {
        log.Fatal(err)
    }
    resp, err := cli.Echo(context.Background(), &echo.Request{Name: "world"})
    if err != nil {
        log.Printf("rpc error: %v", err)
        return
    }
    log.Println(resp.Message) // "Hello world"
}
```
```

--------------------------------

### Kitex Client Direct Addressing

Source: https://context7.com/cloudwego/kitex/llms.txt

Configure the client to connect to a static list of host:port addresses using `client.WithHostPorts`. This bypasses service discovery.

```go
cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("10.0.0.1:8888", "10.0.0.2:8888"),
)
```

--------------------------------

### Structured Logging Interface

Source: https://context7.com/cloudwego/kitex/llms.txt

The `pkg/klog` package provides a structured logging interface. Use `klog.SetLogger` to replace the default logger and `klog.SetLevel` to configure the logging level.

```APIDOC
## `klog` — Structured logging interface

`pkg/klog` defines `FullLogger` and exposes module-level helpers. Replace the default logger by calling `klog.SetLogger`.

```go
import (
    "github.com/cloudwego/kitex/pkg/klog"
    // e.g. zerolog adapter from kitex-contrib
)

// Set a custom logger globally before starting servers/clients:
klog.SetLogger(myZerologAdapter)
klog.SetLevel(klog.LevelWarn)

// Use anywhere in middleware or handlers:
klog.Infof("handling request for method=%s", method)
klog.CtxInfof(ctx, "request id=%s", requestID)
```
```

--------------------------------

### client.WithBackupRequest

Source: https://context7.com/cloudwego/kitex/llms.txt

Sends a second request after a configurable delay if the first has not yet returned, accepting the first response that arrives.

```APIDOC
## client.WithBackupRequest — Backup request policy

Sends a second request after a configurable delay if the first has not yet returned. Accepts the first response that arrives.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/retry"
)

bp := retry.NewBackupPolicy(50 /* delay ms */)
bp.WithMaxRetryTimes(1)

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("127.0.0.1:8888"),
    client.WithBackupRequest(bp),
)
```
```

--------------------------------

### Set Transport Protocol with `client.WithTransportProtocol`

Source: https://context7.com/cloudwego/kitex/llms.txt

Selects the wire protocol for the client. Common values include `transport.TTHeader`, `transport.TTHeaderFramed`, `transport.GRPC`, and `transport.HTTP2`.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/transport"
)

// Force gRPC transport for a protobuf service:
cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("127.0.0.1:8888"),
    client.WithTransportProtocol(transport.GRPC),
)
```

--------------------------------

### Compose Middleware with `endpoint.Middleware` and `endpoint.Chain`

Source: https://context7.com/cloudwego/kitex/llms.txt

Define custom middleware functions and compose them using `endpoint.Chain`. The `Chain` applies middlewares from left to right.

```go
import (
    "context"
    "time"

    "github.com/cloudwego/kitex/pkg/endpoint"
)

func TracingMW(next endpoint.Endpoint) endpoint.Endpoint {
    return func(ctx context.Context, req, resp interface{}) error {
        span := tracer.StartSpan("rpc-call")
        defer span.Finish()
        return next(ctx, req, resp)
    }
}

func RecoveryMW(next endpoint.Endpoint) endpoint.Endpoint {
    return func(ctx context.Context, req, resp interface{}) (err error) {
        defer func() {
            if r := recover(); r != nil {
                err = fmt.Errorf("panic: %v", r)
            }
        }()
        return next(ctx, req, resp)
    }
}

// Chain applies RecoveryMW first, then TracingMW:
combined := endpoint.Chain(RecoveryMW, TracingMW)
```

--------------------------------

### client.WithHostPorts

Source: https://context7.com/cloudwego/kitex/llms.txt

Configures the client to connect to a static list of host:port addresses, bypassing service discovery. This is useful for integration tests or simple deployments.

```APIDOC
## client.WithHostPorts — Direct addressing (bypass service discovery)

Configures the client to dial a static list of host:port addresses, synthesizing an in-memory resolver. Useful for integration tests or scenarios where discovery is not needed.

### Usage Example
```go
cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("10.0.0.1:8888", "10.0.0.2:8888"),
)
```
```

--------------------------------

### server.WithMiddleware

Source: https://context7.com/cloudwego/kitex/llms.txt

Injects a middleware into the server's endpoint chain, which executes for every incoming request before the handler is invoked.

```APIDOC
## server.WithMiddleware — Server-side middleware

Injects a middleware into the server's endpoint chain. Executes for every incoming request before the handler.

```go
import (
    "context"

    "github.com/cloudwego/kitex/server"
    "github.com/cloudwego/kitex/pkg/endpoint"
    "github.com/cloudwego/kitex/pkg/rpcinfo"
)

authMW := func(next endpoint.Endpoint) endpoint.Endpoint {
    return func(ctx context.Context, req, resp interface{}) error {
        ri := rpcinfo.GetRPCInfo(ctx)
        token, _ := ri.From().Tag("token")
        if token != "secret" {
            return errors.New("unauthorized")
        }
        return next(ctx, req, resp)
    }
}

svr := echo.NewServer(&EchoHandler{},
    server.WithServiceAddr(addr),
    server.WithMiddleware(authMW),
)
```
```

--------------------------------

### Configure Client with Failure Retry Policy

Source: https://context7.com/cloudwego/kitex/llms.txt

Enables automatic retry for failed unary calls. Configures max retry count, duration cap, backoff strategy, and per-error predicates.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/retry"
)

fp := retry.NewFailurePolicy()
fp.WithMaxRetryTimes(2)                // up to 2 retries after first attempt
fp.WithMaxDurationMS(500)              // stop retrying after 500 ms total
fp.WithFixedBackOff(10)                // 10 ms fixed backoff between retries

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("127.0.0.1:8888"),
    client.WithFailureRetry(fp),
)
```

--------------------------------

### discovery.Resolver interface

Source: https://context7.com/cloudwego/kitex/llms.txt

Implement this interface to integrate any service registry. The framework caches results and calls `Diff` to compute delta updates for the load balancer.

```APIDOC
## discovery.Resolver interface — Custom service discovery

### Description
Implement this interface to integrate any service registry. The framework caches results and calls `Diff` to compute delta updates for the load balancer.

### Interface Definition
```go
import (
    "context"

    "github.com/cloudwego/kitex/pkg/discovery"
    "github.com/cloudwego/kitex/pkg/rpcinfo"
)

type Resolver interface {
    Target(ctx context.Context, target rpcinfo.EndpointInfo) string
    Resolve(ctx context.Context, desc string) (Result, error)
    Diff(key string, prev, next Result) (Change, bool)
    Name() string
}
```

### Implementation Example
```go
type MyResolver struct{}

func (r *MyResolver) Target(ctx context.Context, target rpcinfo.EndpointInfo) string {
    return target.ServiceName()
}

func (r *MyResolver) Resolve(ctx context.Context, desc string) (discovery.Result, error) {
    instances := []discovery.Instance{
        discovery.NewInstance("tcp", "10.0.0.1:8888", 10, nil),
        discovery.NewInstance("tcp", "10.0.0.2:8888", 10, nil),
    }
    return discovery.Result{Cacheable: true, CacheKey: desc, Instances: instances}, nil
}

func (r *MyResolver) Diff(key string, prev, next discovery.Result) (discovery.Change, bool) {
    return discovery.DefaultDiff(key, prev, next)
}

func (r *MyResolver) Name() string { return "my-resolver" }

// Usage:
cli, _ := echo.NewClient("echo-service", client.WithResolver(&MyResolver{}))
```
```

--------------------------------

### client.WithResolver

Source: https://context7.com/cloudwego/kitex/llms.txt

Plugs a custom service discovery resolver into the client. The framework uses this resolver to discover service endpoints and route requests.

```APIDOC
## client.WithResolver — Custom service discovery

Plugs a `discovery.Resolver` implementation into the client. The framework calls `Resolver.Resolve` on each call and routes through the configured load balancer.

### Usage Example
```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/discovery"
    // e.g. etcd resolver from kitex-contrib:
    etcd "github.com/kitex-contrib/registry-etcd"
)

func main() {
    r, err := etcd.NewEtcdResolver([]string{"127.0.0.1:2379"})
    if err != nil {
        log.Fatal(err)
    }
    cli, err := echo.NewClient("echo-service",
        client.WithResolver(r),
    )
    _ = cli
}
```
```

--------------------------------

### Provide per-call fallback function

Source: https://context7.com/cloudwego/kitex/llms.txt

Use `callopt.WithFallback` to supply a function that executes when an RPC fails, enabling degraded responses instead of errors.

```go
import (
    "github.com/cloudwego/kitex/client/callopt"
    "github.com/cloudwego/kitex/pkg/fallback"
    "github.com/cloudwego/kitex/pkg/rpcinfo"
)

fb := fallback.ErrorFallback(func(ctx context.Context, args utils.KVIterator, result interface{}, err error) (fbResult interface{}, fbErr error) {
    return &echo.Response{Message: "fallback"}, nil
})

resp, err := cli.Echo(ctx, req, callopt.WithFallback(fb))
```

--------------------------------

### client.WithMiddleware

Source: https://context7.com/cloudwego/kitex/llms.txt

Adds a custom `endpoint.Middleware` to the client's invocation chain, which runs for every unary call and is useful for tasks like logging, tracing, or injecting authentication headers.

```APIDOC
## client.WithMiddleware — Client-side middleware

Adds a custom `endpoint.Middleware` to the client's invocation chain. Runs for every unary call; useful for logging, tracing, authentication header injection, etc.

```go
import (
    "context"
    "log"
    "time"

    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/endpoint"
)

loggingMW := func(next endpoint.Endpoint) endpoint.Endpoint {
    return func(ctx context.Context, req, resp interface{}) error {
        start := time.Now()
        err := next(ctx, req, resp)
        log.Printf("rpc finished in %v, err=%v", time.Since(start), err)
        return err
    }
}

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("127.0.0.1:8888"),
    client.WithMiddleware(loggingMW),
)
```
```

--------------------------------

### Set Transport Protocol

Source: https://context7.com/cloudwego/kitex/llms.txt

Use `client.WithTransportProtocol` to select the wire protocol for client connections. Common values include `transport.TTHeader`, `transport.GRPC`, and `transport.HTTP2`.

```APIDOC
## `client.WithTransportProtocol` — Set transport protocol

Selects the wire protocol. Common values are `transport.TTHeader`, `transport.TTHeaderFramed`, `transport.GRPC`, and `transport.HTTP2`.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/transport"
)

// Force gRPC transport for a protobuf service:
cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("127.0.0.1:8888"),
    client.WithTransportProtocol(transport.GRPC),
)
```
```

--------------------------------

### client.WithLoadBalancer

Source: https://context7.com/cloudwego/kitex/llms.txt

Replaces the default weighted-round-robin balancer with a custom implementation that must satisfy the `loadbalance.Loadbalancer` interface.

```APIDOC
## client.WithLoadBalancer — Custom load balancer

Replaces the default weighted-round-robin balancer. Any type implementing `loadbalance.Loadbalancer` is accepted.

```go
import (
    "github.com/cloudwego/kitex/client"
    "github.com/cloudwego/kitex/pkg/loadbalance"
)

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("10.0.0.1:8888", "10.0.0.2:8888"),
    // built-in round-robin:
    client.WithLoadBalancer(loadbalance.NewWeightedRoundRobinBalancer()),
)
```
```

--------------------------------

### Attach a Tracer

Source: https://context7.com/cloudwego/kitex/llms.txt

Use `client.WithTracer` to attach a `stats.Tracer` for receiving RPC call events. This allows integration with tracing systems like OpenTelemetry, Jaeger, or Zipkin.

```APIDOC
## `client.WithTracer` — Attach a tracer

Adds a `stats.Tracer` that receives `Start` and `Finish` events for each RPC call. Integrate with OpenTelemetry, Jaeger, Zipkin, or custom systems via the `kitex-contrib` adapters.

```go
import (
    "github.com/cloudwego/kitex/client"
    oteltrace "github.com/kitex-contrib/obs-opentelemetry/tracing"
)

cli, err := echo.NewClient("echo-service",
    client.WithHostPorts("127.0.0.1:8888"),
    client.WithSuite(oteltrace.NewClientSuite()),
)
```
```

--------------------------------

### JSON generic call without stubs

Source: https://context7.com/cloudwego/kitex/llms.txt

Call Thrift services using JSON-encoded maps without generating Go stubs by providing the IDL file path. Request and response are JSON strings.

```go
import (
    "context"

    "github.com/cloudwego/kitex/client/genericclient"
    "github.com/cloudwego/kitex/pkg/generic"
)

func main() {
    p, err := generic.NewThriftFileProvider("./idl/echo.thrift")
    if err != nil {
        log.Fatal(err)
    }
    g, err := generic.JSONThriftGeneric(p)
    if err != nil {
        log.Fatal(err)
    }
    cli, err := genericclient.NewClient("echo-service", g,
        client.WithHostPorts("127.0.0.1:8888"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Request and response are JSON strings
    resp, err := cli.GenericCall(context.Background(), "Echo",
        `{"name":"world"}`) // `{
```

```go
    if err != nil {
        log.Fatal(err)
    }
    log.Println(resp) // `{"message":"Hello world"}`
}
```

--------------------------------

### Create a New Git Branch

Source: https://github.com/cloudwego/kitex/blob/main/CONTRIBUTING.md

Use this command to create a new branch for your changes based on the main branch.

```bash
git checkout -b my-fix-branch main
```