---
title: "API 客户端和 SDK：不留示例地址"
description: "为什么 api.example-petstore.com 返回 410 Gone，如何将基础网址保存在配置中，以及如何防止示例地址进入生产环境。"
url: https://example-petstore.com/zh/guides/api-base-url
language: zh-Hans
---

# 配置 API 客户端和 SDK

发往 api.example-petstore.com 等地址的请求，来自仍将示例地址用作基础网址的代码。本指南介绍该地址通常位于何处、如何将其移至配置中，以及如何防止此类问题再次发生。

## 您收到的响应

凡是带有请求正文、发往 `/v2/pet` 等 API 式路径或请求 JSON 的请求，都会收到 `410 Gone` 以及一份问题描述（RFC 9457）：

```
HTTP/1.1 410 Gone
Content-Type: application/problem+json; charset=utf-8

{"type":"https://example-petstore.com/#where","title":"Example domain, not a real service",
 "status":410,"detail":"api.example-petstore.com is an example domain used in documentation. …"}
```

此域名并非 Swagger Petstore 示例 API，后者位于 [`petstore.swagger.io`](https://example-petstore.com/zh/guides/swagger-petstore)。

## 地址所在的位置

- 代码中的常量或默认值（`BASE_URL = "https://api.example-petstore.com"`）；
- 从示例中复制的配置文件、`.env` 文件或环境变量；
- 用于生成客户端的 OpenAPI 描述中的 `host` 或 `servers` 字段；
- Postman 或 Insomnia 的环境变量，例如 `{{baseUrl}}`；
- 针对占位地址运行的测试、测试夹具和 CI 作业。

## 正确配置

从配置中读取地址，并在缺少该地址时明确报错：

```
# Python: read the address from configuration, not from the code
import os
BASE_URL = os.environ["API_BASE_URL"]

// JavaScript / Node.js
const baseURL = process.env.API_BASE_URL;
```

```
# Python, httpx
client = httpx.Client(base_url=os.environ["API_BASE_URL"])

// Node.js, axios
const api = axios.create({ baseURL: process.env.API_BASE_URL });

# Generated OpenAPI client (Python)
configuration = Configuration(host=os.environ["API_BASE_URL"])
```

在 Postman 或 Insomnia 中，请为每个环境分别设置 `baseUrl`，并在发送请求前选择正确的环境。

## 预防措施

添加一项启动检查或测试检查，拒绝示例地址：

```
import os, re
base = os.environ["API_BASE_URL"]
if re.search(r"example-(petstore|commerce-host)\.com", base):
    raise RuntimeError(f"API_BASE_URL still points at an example domain: {base}")
```

在您自己的文档和示例中，请使用专为此用途保留的名称，例如 `api.example.com`。请参阅[示例域名](https://example-petstore.com/zh/example-domains)。

## 已发送的密钥

如果请求中携带了 API 密钥、令牌、密码或会话 Cookie，那么它们已被发送到错误的服务器。请在签发它们的服务中将其撤销，并签发新的凭据。[凭据泄露：现在该怎么办](https://example-petstore.com/zh/guides/leaked-credentials)。

不依赖真实服务进行测试： [用 Mock API 测试，而不是示例地址](https://example-petstore.com/zh/guides/mock-api)

## 来源

- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html) IETF
- [Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) OWASP
- [Swagger Petstore sample API](https://petstore.swagger.io/) Swagger