Nami - 异常处理与排障

Nami 调用失败可先按请求链路分层：代理构建、地址解析、通道连接、HTTP 响应、响应解码。每层的检查项不同。

1、异常分类

• NamiException：Nami 配置、通道或调用过程中的基础异常。
• NamiResponseException：收到状态码大于等于 400 的响应，可通过 getCode() 和 getDescription() 读取信息。
• NamiDecodeException：响应已经收到，但无法按目标类型解码。
• 服务端业务异常：RPC 返回的异常对象可能在客户端重新抛出，具体表现取决于编码器和异常类型。

try {
    User user = userService.getById(1L);
} catch (NamiResponseException e) {
    log.warn("remote status={}, description={}", e.getCode(), e.getDescription());
} catch (NamiException e) {
    log.error("nami call failed", e);
}

2、排障路径

1. 先使用固定 url，确认服务端接口本身可访问。
2. 检查 @NamiClient 的 url 或 group/name/path 是否配置完整。
3. 检查方法路径、HTTP 方法、请求头和 @Body 参数绑定。
4. 检查 HTTP channel 与 coder 是否已引入，并确认响应 Content-Type 能匹配 decoder。
5. 最后再排查注册发现、过滤器、负载均衡和超时。

3、日志建议

生产日志至少关联：服务名、路径、HTTP 方法、耗时、状态码和 traceId。不要记录密码、令牌、Cookie、完整请求体或文件内容。对连接异常保留 cause，便于区分 DNS、连接拒绝和读取超时。

业务写操作不要默认重试。只有在确认接口幂等、超时语义明确且服务端能防重时，才应在业务层实现重试。