---
title: "Nami - 异常处理与排障"
---

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

### 1、异常分类

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

```java
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、连接拒绝和读取超时。

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