HTTP API 总览

🌐 `pkg/api` — 把 snir 暴露为 HTTP 服务。

pkg/api 基于 gorilla/mux 提供 HTTP 接口，让非 Go 程序也能调用 snir，支持鉴权、并发限流、队列。

📁 源码目录：pkg/api/

文件结构

文件	源码	职责
types.go	types.go	请求/响应/Server 类型
server_methods.go	server_methods.go	Server 方法、路由
server.go	server.go	健康统计、并发入口
screenshot.go	screenshot.go	截图端点
batch.go	batch.go	批量端点
concurrency.go	concurrency.go	并发限流器
middleware.go	middleware.go	鉴权中间件
helpers.go	helpers.go	辅助函数

端点一览

方法	路径	说明	详解
POST	/screenshot	单次截图	→
GET	/screenshot/:id	取已存截图	→
GET	/screenshots	列出截图	→
POST	/batch	批量截图	→
GET	/health	健康检查	→
GET	/stats	统计	→
GET	/results	历史结果列表	→
GET	/results/{id}	按 id 检索历史结果	→
GET	/results/by-url	按 URL 查询历史	→
GET	/results/by-host	按 host 模糊查询历史	→

请求处理链

一次请求的完整时序

下图展示一次 HTTP API 请求从接入到返回的完整链路：调用方发起请求，依次穿过鉴权、并发限流中间件，进入 Handler 后由 Server 调用 Driver 完成截图，再沿原路返回 JSON 响应。

启动

生产启动最小参数

snir api --host 127.0.0.1 --port 8080 \
  --api-key $(openssl rand -hex 32) \
  --max-concurrent 10 --queue-size 100

• --host 127.0.0.1：仅本机，公网暴露交给反代
• --api-key：强随机，勿用弱口令
• --max-concurrent：建议 ≤ Chrome 池大小，否则请求排队

见 CLI api 与 安全。

内部视角

实现细节见 pkg/api（内部）。

下一步

• Server 与选项
• 请求类型
• 鉴权
• 并发限流
• POST /screenshot