fastapi应用启动失败导致客户端请求报错“connection refused”，根本原因是请求代码与服务启动逻辑混在同一文件中，导致请求在服务器尚未就绪时即发起。本文提供正确分离服务与测试代码的方法，并给出完整可运行示例。
在使用 FastAPI 构建本地机器学习预测服务时，一个常见但易被忽视的错误是：将客户端请求代码（如 requests.post()）与服务定义写在同一 Python 文件中，并直接通过 uvicorn main:app --reload 启动。这会导致程序在 Uvicorn 尚未完成服务器初始化前，就执行了 HTTP 请求，而此时 localhost:8000 尚未监听任何端口，Windows 系统因此返回 [WinError 10061] No connection could be made because the target machine actively refused it —— 即“目标机器主动拒绝连接”。
✅ 正确做法是严格分离「服务端」与「客户端」逻辑：
- 服务端文件（main.py）仅负责定义 API 和启动服务，不包含任何 requests 调用；
- 客户端请求应独立运行（如通过 Postman、curl 或单独的 test_client.py 文件）。
以下是重构后的推荐结构：
? main.py（纯服务端，无请求逻辑）：
from fastapi import FastAPI
import pickle
import numpy as np
from typing import List
app = FastAPI()
def predict(data: List[float]) -> int: # 假设模型输出为整数标签
with open("model.pkl", "rb") as f:
model = pickle.load(f)
data_array = np.array(data).reshape(1, -1)
prediction = model.predict(data_array)[0] # 返回标量而非数组
return int(prediction)
@app.post("/predict")
def predict_route(data: List[float]):
pred = predict(data)
return {"prediction": pred}? test_client.py（独立客户端，用于验证）：
import requests
import json
# 确保先运行 uvicorn main:app --reload，再执行此脚本
with open('test_data.json') as f:
test_data = json.load(f) # 格式应为 [1.2, 3.4, 5.6, ...]
try:
response = requests.post("http://localhost:8000/predict", json=test_data)
response.raise_for_status() # 抛出HTTP错误（如400/500）
print("✅ 成功响应:", response.json())
except requests.exceptions.ConnectionError:
print("❌ 连接失败：请确认 FastAPI 服务已启动（uvicorn main:app --reload）且端口未被占用。")
except requests.exceptions.HTTPError as e:
print(f"❌ HTTP 错误: {e}")⚠️ 注意事项：
- ✅ 运行顺序必须为：先启动服务 → uvicorn main:app --reload（保持终端运行）→ 再执行 python test_client.py；
- ✅ test_data.json 应为一维浮点数列表（如 [2.1, 0.8, 3.3]），与模型输入维度一致；
- ✅ 若端口 8000 被占用，可通过 --port 8001 指定其他端口；
- ⚠️ 避免在 main.py 中 import requests 并调用 post() —— 这会破坏 FastAPI 的异步生命周期，引发竞态条件。
总结：FastAPI 是异步 Web 框架，其服务启动是延迟且非阻塞的。将测试逻辑耦合进服务文件，本质上是“让服务器自己给自己发请求”，而该请求必然早于服务就绪时间点，从而必然失败。遵循关注点分离原则，即可彻底规避此类连接异常。
