Express API Integration Lab

English | 简体中文

一个面向 Node.js 初学者和 API 集成练习者的小型 Express 学习实验室：用同一套前后端展示本地计算、免密公共 API 与受限 AI 代理三种后端模式。

项目状态：Demo / Learning Lab，版本 0.1.0。 这是教学参考实现，不是可直接托管到公网的公共 API 或 AI 网关。排序功能完全离线；天气需要网络；AI 对话默认关闭，只有服务器所有者配置自己的凭据后才启用并可能产生费用。

无密钥、无定位的首页安全预览

截图使用 ?preview=1 生成，不请求浏览器定位、不配置 AI Key，也不包含个人数据。

为什么值得看

很多 API 教程只展示“请求成功”的理想路径。这个项目同时保留了可以运行的页面，并把输入校验、外部请求超时、统一错误结构、日志脱敏、依赖注入、Mock 测试和 AI 成本边界放进一个足够小的代码库中。

示例	后端模式	学习价值	外部依赖
数值排序	本地计算	请求校验、纯逻辑响应、错误契约	无
当前天气	公共 API 聚合	坐标校验、超时、上游故障降级、响应裁剪	Open-Meteo 与网络
AI 对话	带密钥的服务端代理	凭据隔离、输入预算、输出上限、限流、上游错误脱敏	用户自己的 Ark 凭据，可能收费

适合：Express 入门、前后端联调、API 代理与错误处理练习。它不适合：公开托管多人共享的 AI 代理、生产监控服务或需要账户/持久化数据的应用。

能力边界

没有用户认证、数据库、持久化限流、计费配额或后台管理。
AI 限流保存在单个 Node.js 进程的内存中，重启会清空，多实例之间不会同步。
页面通过 CDN 加载 Bootstrap；离线启动时后端仍可用，但页面样式可能需要网络。
天气接口会把浏览器定位发给 Open-Meteo。请只在理解其隐私影响后授权定位。
/api/deepseek 仅为旧页面兼容别名；新代码应使用 /api/chat。
默认监听 127.0.0.1。不要在没有认证、持久化限流、TLS 和反向代理的情况下直接暴露到公网。
非本机部署还必须使用持久化共享配额/限流和服务商预算告警；当前进程内计数不能承担费用保护责任。

快速开始（无需 API Key）

前置条件：Node.js 20 或更高版本，npm 10 或更高版本。

npm ci
npm start

打开 http://127.0.0.1:3000。不创建 .env 也能启动并使用排序；AI 卡片会显示未配置提示。

另开终端验证健康检查和离线排序：

curl http://127.0.0.1:3000/health
curl -X POST http://127.0.0.1:3000/api/sort \
  -H "Content-Type: application/json" \
  -d '{"numbers":"3, 1, 2","order":"asc"}'

预期排序结果中的 result 为 [1,2,3]。Windows PowerShell 也可使用：

Invoke-RestMethod http://127.0.0.1:3000/health
Invoke-RestMethod http://127.0.0.1:3000/api/sort -Method Post `
  -ContentType 'application/json' -Body '{"numbers":"3, 1, 2","order":"asc"}'

可选配置

只有需要 AI 功能时才复制配置模板：

cp .env.example .env

Windows PowerShell：

Copy-Item .env.example .env

变量	默认值	说明
`HOST`	`127.0.0.1`	HTTP 监听地址
`PORT`	`3000`	HTTP 端口
`UPSTREAM_TIMEOUT_MS`	`8000`	天气与 AI 上游超时，限制为 100–30000 ms
`ARK_API_KEY`	空	可选的 Ark API Key；也兼容旧变量 `DEEPSEEK_API_KEY`
`ARK_MODEL`	空	Ark 模型或推理接入点 ID；也兼容 `DEEPSEEK_MODEL`
`ARK_API_BASE_URL`	Ark 北京端点	服务端基础 URL
`AI_MAX_MESSAGE_CHARS`	`2000`	单条消息和历史消息的字符上限
`AI_MAX_HISTORY_ITEMS`	`10`	单次请求携带的历史条数上限
`AI_MAX_OUTPUT_TOKENS`	`1024`	调用者可请求的输出 Token 硬上限
`AI_DEFAULT_OUTPUT_TOKENS`	`512`	未指定时的输出预算，不会超过硬上限
`AI_RATE_LIMIT_MAX`	`10`	每个进程内、每个客户端在窗口内的 AI 请求数
`AI_RATE_LIMIT_WINDOW_MS`	`60000`	内存限流窗口
`AI_ALLOWED_HOSTS`	本机回环主机	AI 请求允许的逗号分隔 Host；非本机监听时必须显式设置
`AI_ALLOWED_ORIGINS`	空	非本机浏览器调用允许的精确 Origin，逗号分隔

.env 已被 Git 忽略。若你从旧项目副本继承过真实 DEEPSEEK_API_KEY，请先在服务商控制台吊销或轮换，不能仅靠删除本地文件解决泄露风险。

API 示例

`POST /api/sort`

{
  "numbers": "8, 3, 5",
  "order": "desc"
}

最多接受 100 个有限数值，order 只能是 asc 或 desc。

`GET /api/weather?lat=31.23&lon=121.47`

经纬度分别限制在 [-90, 90] 与 [-180, 180]。反向地理编码失败时仍返回天气，主要天气请求失败或超时时返回统一的 502/504 错误。

天气数据来自 Open-Meteo，页面和 API 响应均包含来源说明。

`POST /api/chat`

{
  "message": "用一句话解释 Express 中间件",
  "history": [{ "role": "assistant", "content": "可以。" }],
  "max_completion_tokens": 256,
  "reasoning_effort": "low"
}

服务器只接受纯文本 user/assistant 历史；不会把上游响应正文或内部错误原样返回浏览器。

AI 路由只接受 application/json。默认本机模式只接受 localhost、127.0.0.1 或 ::1 Host；带 Origin 的浏览器请求必须来自本机允许主机。CLI/原生客户端可以不发送 Origin，但仍须通过 Host 校验和频率限制。非本机部署必须显式设置允许列表，并在此策略之外增加真实认证与持久化共享配额。

所有 API 错误使用相同结构：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "可安全展示的错误说明",
    "requestId": "用于定位本次请求的 ID"
  }
}

架构

flowchart LR
  Browser["浏览器页面"] --> App["Express app"]
  App --> Sort["本地排序路由"]
  App --> Weather["天气服务"]
  App --> Chat["受限 AI 服务"]
  Weather --> OpenMeteo["Open-Meteo"]
  Chat --> Ark["Volcengine Ark"]

src/
├─ app.js                 # 组合中间件、服务和路由；不监听端口
├─ server.js              # 读取本地环境并管理进程生命周期
├─ config.js              # 有边界的配置解析
├─ lib/                   # 错误、校验、超时请求、内存限流
├─ routes/                # HTTP 输入/输出层
└─ services/              # Open-Meteo 与 Ark 上游适配
test/app.test.js          # 无真实外部调用的 HTTP 集成测试
scripts/                  # 语法、冒烟与发布面扫描

更详细的设计和威胁边界见 docs/architecture.md。

质量验证

npm run lint
npm test
npm run test:coverage
npm run smoke
npm run security:scan
npm run verify

测试通过依赖注入 Mock 天气与 AI 响应，不访问真实外部服务、不使用真实 Key、不产生模型费用。CI 在 Node.js 20 和 22 上从 lockfile 全新安装并运行 npm run verify。

安全与贡献

漏洞请按 SECURITY.md 私下报告；不要在公开 Issue 粘贴密钥或完整请求内容。
开发环境、提交约定与 PR 门禁见 CONTRIBUTING.md。
发布前审计状态见 docs/release-audit.md。其中“旧密钥已由服务商侧轮换”和“素材/代码权利确认”必须由仓库所有者完成。

Roadmap

用持久化共享限流替代单进程 Map；
增加服务端指标、结构化日志和可配置允许来源；
将 CDN 前端依赖固定到本地构建产物；
补充使用合成数据生成、可重复制作的脱敏界面截图；
在不破坏教学可读性的前提下增加更多失败场景测试。

项目来源与许可证

本项目由一个包含排序、天气和 AI 问答的课程 Demo 演化而来。当前目标是提供可审阅的 API 集成参考，而不是包装成统一商业产品。

代码计划以 MIT License 发布。仓库公开前，所有者仍须完成 docs/release-audit.md 中的原创性与第三方权利确认。