Cpte-Boot/cpte-wms-service/LOCAL_DEV_FEIGN_CONFIG.md

# 本地开发环境 Feign 配置指南

## 📋 问题描述

在本地开发环境测试时，Feign Client 调用失败，报错：

```
Couldn't resolve host: wms-basic-service
```

## 🔍 原因分析

**K8s Service 名称无法在本地解析**

- `wms-basic-service` 是 Kubernetes Service 的名称
- 这个名称只能在 K8s 集群内部通过 CoreDNS 解析
- 本地开发环境（localhost）无法解析 K8s 服务名

## ✅ 解决方案

### 方案一：配置本地服务地址（推荐）

#### 1. 修改 application-dev.yml

在入库服务的 `application-dev.yml` 中已添加 Feign 配置：

```yaml
# Feign 客户端配置（本地开发环境使用 localhost）
feign:
  client:
    config:
      default:
        connectTimeout: 5000
        readTimeout: 10000
        loggerLevel: BASIC
    # 本地开发环境服务地址配置
    wms-basic:
      url: http://localhost:8001
    wms-inventory:
      url: http://localhost:8004
    wms-schedule:
      url: http://localhost:8005
```

#### 2. 启动所有需要的服务

确保以下服务已在本地启动：

```bash
# 基础服务 - 端口 8001
cpte-wms-service/cpte-wms-basic-service

# 入库服务 - 端口 8002
cpte-wms-service/cpte-wms-inbound-service

# 出库服务 - 端口 8003
cpte-wms-service/cpte-wms-outbound-service

# 库存服务 - 端口 8004
cpte-wms-service/cpte-wms-inventory-service

# 调度服务 - 端口 8005
cpte-wms-service/cpte-wms-schedule-service
```

#### 3. 测试 Feign 调用

现在可以通过 Feign Client 正常调用其他服务了：

```java
@Autowired
private BasicServiceClient basicServiceClient;

// 调用基础服务
Result<Map<String, Object>> result = basicServiceClient.getItemById("item123");
```

### 方案二：使用 Host 文件映射（不推荐）

修改本地 Host 文件，将 K8s 服务名映射到 localhost：

**Windows**: `C:\Windows\System32\drivers\etc\hosts`
**Linux/Mac**: `/etc/hosts`

```
127.0.0.1  wms-basic-service
127.0.0.1  wms-inventory-service
127.0.0.1  wms-schedule-service
```

**缺点**：
- 需要修改系统文件，可能需要管理员权限
- 所有服务都映射到 localhost，无法区分不同服务
- 不便于多环境管理

## 🎯 Feign Client 配置说明

### 配置优先级

Feign Client 的 URL 配置优先级如下：

1. **配置文件指定**（最高优先级）
   ```yaml
   feign.client.wms-basic.url: http://localhost:8001
   ```

2. **@FeignClient 注解的 url 属性默认值**
   ```java
   @FeignClient(
       name = "wms-basic-service",
       url = "${feign.client.wms-basic.url:http://wms-basic-service:80}"
   )
   ```

3. **服务发现**（如果使用了 Nacos/Eureka）
   - 通过服务名自动发现

### 环境隔离配置

#### 开发环境 (application-dev.yml)

```yaml
feign:
  client:
    wms-basic:
      url: http://localhost:8001
    wms-inventory:
      url: http://localhost:8004
    wms-schedule:
      url: http://localhost:8005
```

#### 测试环境 (application-test.yml)

```yaml
feign:
  client:
    wms-basic:
      url: http://test-wms-basic:80
    wms-inventory:
      url: http://test-wms-inventory:80
    wms-schedule:
      url: http://test-wms-schedule:80
```

#### 生产环境/K8s (application-k8s.yml)

```yaml
feign:
  client:
    # 不配置 url，使用 K8s Service 名称（通过 CoreDNS 解析）
    wms-basic:
      # 默认值：http://wms-basic-service:80
    wms-inventory:
      # 默认值：http://wms-inventory-service:80
    wms-schedule:
      # 默认值：http://wms-schedule-service:80
```

## 🧪 测试方法

### 1. 使用 Swagger/Knife4j 测试

启动入库服务后，访问：

```
http://localhost:8002/doc.html
```

找到 Feign 调用相关的接口进行测试。

### 2. 使用 Postman 测试

```bash
# 调用入库服务接口
POST http://localhost:8002/api/wms/inbound/test

# 请求体
{
  "itemId": "item123",
  "quantity": 100
}
```

### 3. 使用 curl 测试

```bash
curl -X POST http://localhost:8002/api/wms/inbound/test \
  -H "Content-Type: application/json" \
  -d '{"itemId":"item123","quantity":100}'
```

### 4. 查看 Feign 日志

配置日志级别查看 Feign 调用详情：

```yaml
logging:
  level:
    org.cpte.feign.client: DEBUG
    feign: DEBUG
```

日志输出示例：

```
DEBUG: [BasicServiceClient] ---> GET http://localhost:8001/api/wms/basic/item/item123
DEBUG: [BasicServiceClient] <--- 200 OK (150ms)
DEBUG: [BasicServiceClient] {"code":200,"message":"success","result":{...}}
```

## ⚠️ 常见问题

### Q1: Connection refused

**错误**: `ConnectException: Connection refused`

**原因**: 目标服务未启动

**解决**: 
```bash
# 检查服务是否启动
netstat -an | grep 8001

# 启动基础服务
cd cpte-wms-service/cpte-wms-basic-service
mvn spring-boot:run
```

### Q2: Read timed out

**错误**: `ReadTimeoutException: Read timed out`

**原因**: 服务响应超时

**解决**: 增加超时时间
```yaml
feign:
  client:
    config:
      default:
        connectTimeout: 10000  # 连接超时 10 秒
        readTimeout: 30000     # 读取超时 30 秒
```

### Q3: Couldn't resolve host

**错误**: `UnknownHostException: Couldn't resolve host`

**原因**: 服务地址配置错误

**解决**: 检查配置文件中的 URL 是否正确
```yaml
feign:
  client:
    wms-basic:
      url: http://localhost:8001  # 确保地址和端口正确
```

## 📊 服务端口列表

| 服务名称 | 端口 | 说明 |
|---------|------|------|
| wms-basic-service | 8001 | 基础服务 |
| wms-inbound-service | 8002 | 入库服务 |
| wms-outbound-service | 8003 | 出库服务 |
| wms-inventory-service | 8004 | 库存服务 |
| wms-schedule-service | 8005 | 调度服务 |

## 🚀 快速开始

### 1. 启动所有服务

```bash
# 终端 1 - 基础服务
cd cpte-wms-service/cpte-wms-basic-service
mvn spring-boot:run

# 终端 2 - 入库服务
cd cpte-wms-service/cpte-wms-inbound-service
mvn spring-boot:run

# 终端 3 - 库存服务
cd cpte-wms-service/cpte-wms-inventory-service
mvn spring-boot:run

# 终端 4 - 调度服务
cd cpte-wms-service/cpte-wms-schedule-service
mvn spring-boot:run
```

### 2. 访问 Swagger 文档

```
基础服务：http://localhost:8001/doc.html
入库服务：http://localhost:8002/doc.html
出库服务：http://localhost:8003/doc.html
库存服务：http://localhost:8004/doc.html
调度服务：http://localhost:8005/doc.html
```

### 3. 测试 Feign 调用

在入库服务的 Swagger 中测试调用基础服务的接口。

## 📖 相关文档

- [Feign 使用指南](cpte-wms-service/FEIGN_USAGE.md)
- [Spring Cloud 版本兼容性修复](cpte-wms-service/SPRING_CLOUD_VERSION_FIX.md)
- [K8s 部署文档](K8S_DEPLOYMENT.md)

## 🎉 总结

✅ **本地开发环境**：使用 `localhost` + 端口号配置 Feign Client URL

✅ **K8s 环境**：使用 K8s Service 名称（通过 CoreDNS 自动解析）

✅ **配置隔离**：通过不同环境的配置文件（dev/test/k8s）实现环境隔离

✅ **灵活切换**：通过配置文件即可切换不同环境，无需修改代码

现在可以在本地正常测试 Feign 调用了！🎊