example-petstore.com

示例域名 · 并非真实服务 · 浏览器访问显示此页面 · API 请求返回 410 Gone

指南 · 文档

可以放心使用的示例值

文档、教程和测试需要一些看起来真实、却永远不会联系到任何人的地址、号码和名称。大多数类型的值都有专门保留的范围。本指南逐一列出这些范围并注明来源，这样即使有人复制了示例，也不会造成任何危害。

为什么要用保留值

示例会被复制：复制到代码、配置文件、测试和其他文档中。一个看似虚构、实则属于某人的值，会把相应的流量、电子邮件或电话送到真实的第三方手中。example-petstore.com 就是一个例子：它是 Google 文档中的一个虚构名称，任何人都可以注册，至今仍在接收请求。保留值保证永远不会被分配出去，因此被复制的示例只会无害地失败。

域名与电子邮件

示例中的网站、API 和电子邮件地址请使用 example.com、example.net 或 example.org 及其子域名，例如 api.example.com 和 user@example.com。测试环境、绝不能被解析的名称以及本地网络可以使用 .test、.invalid、.localhost、home.arpa 和 .internal。

每个保留名称的用途，以及为什么像 example-petstore.com 这样的形似名称并不安全： 示例域名

IP 地址

类型为文档保留来源
IPv4192.0.2.0/24（TEST-NET-1）、198.51.100.0/24（TEST-NET-2）、203.0.113.0/24（TEST-NET-3）RFC 5737
IPv62001:db8::/32RFC 3849
IPv6（较大的网络）3fff::/20RFC 9637 (2024)
 
# 示例中的一个客户端、一个服务器和一个代理
client   192.0.2.10        2001:db8::10
server   198.51.100.20     2001:db8:1::20
proxy    203.0.113.30      2001:db8:2::30

这三个 IPv4 地址块可以在示例中构成三个独立的“网络”，便于讲解路由或防火墙。之所以有 3fff::/20，是因为 2001:db8::/32 太小，无法展示大型运营商的真实地址分配。

AS 号

BGP 示例可使用 64496–64511（16 位）和 65536–65551（32 位），它们由 RFC 5398 保留用于文档。私有 AS 号是给真实网络使用的，不适合用作示例。

MAC 地址

00-00-5E-00-53-00 至 00-00-5E-00-53-FF（在大多数工具中写作 00:00:5e:00:53:00）由 RFC 9542（取代了 RFC 7042）保留用于文档。

电话号码

全球并没有统一的号段；一些国家为影视作品和示例保留了各自的号段：

  • 美国和加拿大：555-0100 至 555-0199，可搭配任意区号，例如 +1 202 555 0143。
  • 英国（Ofcom）：手机号码 07700 900000 至 07700 900999，伦敦 020 7946 0000 至 020 7946 0999，以及不属于特定地区的 01632 960000 至 01632 960999。

其他国家请查询当地的电信监管机构。如果没有保留号段，请使用无法拨通的占位符，例如 +31 6 XXXX XXXX，而不要使用只是看起来随机的数字。

支付卡

支付服务商会公布只在其测试模式下有效的测试卡号，例如 Stripe 的 4242 4242 4242 4242，可搭配任意未来的到期日期和任意 CVC。请使用您所集成的服务商提供的卡号；一家服务商的测试卡号不会被另一家接受。切勿在文档、测试夹具或截图中使用真实卡号，即使是您自己的也不行。

不应使用的值

  • 虚构的形似域名，例如 example-petstore.com、mycompany.com 或 test.com：它们可以被注册，而且往往已经被注册。
  • 在公开文档中使用私有地址段，例如 10.0.0.0/8 或 192.168.0.0/16：这些地址存在于读者自己的网络中，被复制的示例可能会访问到那里的真实设备。
  • 看起来真实的 API 密钥：请写明确的占位符，例如 YOUR_API_KEY 或 sk_test_…，切勿使用曾经有效的密钥。
  • 真实人员的数据：同事或客户的姓名、电子邮件地址和电话号码不应出现在示例或测试夹具中。

来源