墨西哥邮政编码 API 🇲🇽

基于 Python 3.12、FastAPI、SQLite WAL 模式 和 Docker 构建的超快速 RESTful API，旨在以 < 1 毫秒 的速度响应墨西哥官方邮政编码、定居点、市镇和州目录。

📜 法律归属条款（CC BY 4.0 强制要求）

本 API 使用并处理来自墨西哥邮政服务 (SEPOMEX) 通过 datos.gob.mx 发布的官方目录的地理和邮政编码信息，该目录采用 Creative Commons Attribution 4.0 International 许可。

🚀 主要特性

• API 合同与规范： docs/api_contract.md

• 速度与性能： 使用 SQLite 预写日志 (WAL) 模式和 orjson 序列化实现亚毫秒级响应时间。

• 网络安全： OWASP 加固、安全标头、速率限制、Pydantic v2 严格正则表达式验证和 Docker 非 root 用户。

• 企业级错误处理： RFC 7807（问题详情）格式，每个请求附带唯一的 X-Correlation-ID。

• 审计与日志： 通过 loguru 提供结构化 JSON 日志，每天午夜 (00:00) 轮换，.zip 压缩，保留 30 天。

• 死锁预防： 仅读模式 (mode=ro) 的 HTTP 连接，带 PRAGMA busy_timeout=5000;。

• 自动数据摄取脚本： 原子方式下载、清理（ISO-8859-1 转 UTF-8）并填充数据库。

📦 本地安装与运行

1. 前提条件

• Python 3.10+

• Virtualenv 或 Docker

2. 配置环境并安装依赖

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. 执行数据摄取（SEPOMEX / datos.gob.mx）

python scripts/ingest_sepomex.py

此命令将下载官方 CPdescarga.txt 文件并生成 sepomex.db，包含超过 148,000 个定居点和优化索引。

4. 启动开发服务器

uvicorn app.main:app --reload --port 8000

访问交互式文档：http://localhost:8000/docs

🐳 使用 Docker 运行

选项 A：Docker 构建与运行

docker build -t codigos-postales-api .
docker run -p 8000:8000 codigos-postales-api

选项 B：Docker Compose

docker-compose up -d

🔐 认证与速率限制（API 密钥与 JWT）

本 API 具有可从 .env 配置的混合认证方案：

1. 运行模式 (REQUIRE_AUTH)

• REQUIRE_AUTH=False（公共 API 模式，默认）： 端点可自由访问。请求控制通过 基于 IP 的速率限制（默认 120 次/分钟）实现。

• REQUIRE_AUTH=True（企业保护 API 模式）： 每个请求必须在标头中发送有效凭据。

2. 支持的认证选项

1. X-API-Key 标头：

   curl -H "X-API-Key: key-dev-12345" http://localhost:8000/api/v1/codigo-postal/01000

2. JWT Bearer 令牌 (Authorization: Bearer <token>)：

   • 兑换 JWT 令牌（有效期 24 小时）：

     curl -X POST http://localhost:8000/api/v1/auth/token -H "X-API-Key: key-dev-12345"

   • 使用返回的令牌发起请求：

     curl -H "Authorization: Bearer <tu_jwt_token>" http://localhost:8000/api/v1/codigo-postal/01000

🛠️ 可用端点

📦 官方 SDK 客户端 (mx-postal-client)

该项目包含两个轻量级 SDK 客户端包，可轻松消费 API，无需手动编写 HTTP 请求：

• Python SDK (sdk/python)：

  pip install ./sdk/python

  from mx_postal_client import MXPostalClient
  client = MXPostalClient(base_url="http://localhost:8080")
  cp_data = client.get_codigo_postal("01000", colonia="San Ángel")

• TypeScript / Node.js SDK (sdk/typescript)：

  npm install ./sdk/typescript

  import { MXPostalClient } from 'mx-postal-client';
  const client = new MXPostalClient({ baseUrl: 'http://localhost:8080' });
  const detail = await client.getCodigoPostal('01000');

🤖 与 AI 代理集成（模型上下文协议 - MCP）

该 API 配备了一个官方 MCP 服务器 (scripts/mcp_server.py)，允许 AI 代理（Claude Desktop、ChatGPT、Antigravity IDE、LangChain、AutoGPT）以自然语言查询和交互墨西哥官方地理数据库。

为 AI 暴露的工具：

1. consultar_codigo_postal(cp)：返回完整地理信息卡片和聚居区列表。

2. validar_direccion_postal(codigo_postal, colonia, estado, municipio)：实时验证数据与 SEPOMEX 的一致性。

3. buscar_asentamientos_por_nombre(nombre_colonia, limite)：基于关键词的自然语言搜索。

在 Claude Desktop / Antigravity IDE (mcp.json) 中的配置：

{
  "mcpServers": {
    "mx-postal-codes": {
      "command": "python3",
      "args": ["/ruta/absoluta/a/codigos-postales-api/scripts/mcp_server.py"]
    }
  }
}

🔄 SEPOMEX 目录自动验证

容器在后台运行一个异步月度计划任务，检查 datos.gob.mx 上是否有更新，不影响 HTTP 延迟（< 1 毫秒）。

要手动执行验证或强制在 Docker 容器内更新目录：

docker exec codigos_postales_api python3 scripts/check_updates.py --force

🏆 与当前技术状态比较（2026）

我们的解决方案与当前市场上开源替代品和商业 SaaS 服务的技术比较：

🔬 实验

该项目包含一套完整的负载测试、GPS 地理围栏、税务标准化和与人工智能代理 (MCP) 的互操作性测试。

• 阶段 1 (延迟与批量)： 批量验证 (POST /batch-validate) 加速 58.91 倍。

• 阶段 2 (SAT 标准化)： 算法 $F_1$ 分数达到 90.45%，在包含 1,000 个含噪样本的数据集上精确度 100%。

• 阶段 3 (AI 代理 / MCP)： 通过 MCP 服务器交互时，令牌节省 99.43%。

🧪 运行测试

pytest