代码地图
先阅读沿一次真实发信请求走到底掌握请求穿透五道防线的行为顺序,再使用本页定位职责边界、核心符号与验证入口。本代码地图覆盖 Worker 运行时源码与离线回归测试全部第一方代码。
| 路径 | 职责 | 关键代码 | 与主流程的关系 |
|---|---|---|---|
src/ | HTTP 请求编排、配置解析、IP 匹配、字段校验与统一信封输出 | 请求入口(仓库文件:src/index.ts)、配置解析(仓库文件:src/config.ts)、字段校验(仓库文件:src/validate.ts) | 实现主流程全部五步校验、错误分类与发信绑定调用 |
test/ | 离线 Vitest 回归套件,使用假绑定覆盖配置、CIDR、字段与请求流水线 | 管线测试(仓库文件:test/handler.test.ts)、配置测试(仓库文件:test/config.test.ts)、校验测试(仓库文件:test/validate.test.ts) | 证明主流程成功路径及各类 4xx/502/503 错误分支按约定触发 |
src/
| 重要代码 | 功能 | 关键符号 | 调用方 / 使用方 |
|---|---|---|---|
src/index.ts(仓库文件:src/index.ts) | Worker 唯一 default 导出与路由、鉴权、限流、发信串联 | handleSend, handleHealth, tokenMatches, sendMessage | Cloudflare Workers 运行时;处理器测试(仓库文件:test/handler.test.ts) |
src/config.ts(仓库文件:src/config.ts) | 解析绑定与环境变量,供请求路径与体检接口共享同一套判据 | loadConfig, inspectConfig, senderDomainAllowed, TOKEN_PATTERN | src/index.ts、src/validate.ts;配置测试(仓库文件:test/config.test.ts) |
src/ip.ts(仓库文件:src/ip.ts) | 解析纯文本 IPv4/IPv6 与 CIDR,执行掩码位比对及坏配置报错 | parseIpAddress, parseAllowlist, isIpAllowed, matchesNetwork | src/config.ts、src/index.ts;IP 测试(仓库文件:test/ip.test.ts) |
src/validate.ts(仓库文件:src/validate.ts) | 严格校验证件外框、UTF-8 字节上限、地址语法与两套报文映射 | buildStandardMessage, buildPanelMessage, STANDARD_FIELDS, PANEL_FIELDS | src/index.ts;校验测试(仓库文件:test/validate.test.ts) |
src/errors.ts(仓库文件:src/errors.ts) | 定义面向调用方、校验层与配置层的三段式错误类与对外错误码 | RelayError, FieldError, ConfigError, RelayErrorCode | src/ 全部业务模块;响应模块(仓库文件:src/respond.ts) |
src/respond.ts(仓库文件:src/respond.ts) | 构造统一成功/失败 JSON 信封及安全响应头 | okResponse, errorResponse, SuccessEnvelope, ErrorEnvelope | src/index.ts;处理器测试(仓库文件:test/handler.test.ts) |
src/log.ts(仓库文件:src/log.ts) | 输出单行 JSON 结构化事件,强制屏蔽令牌与正文原文 | logEvent, LogLevel | src/index.ts;处理器测试(仓库文件:test/handler.test.ts) |
改动路由顺序、鉴权提取或绑定错误处理时,从 src/index.ts(仓库文件:src/index.ts) 入手并运行 pnpm test -- test/handler.test.ts;改动环境变量规则或 /healthz 就绪项时,同时保持 loadConfig 与 inspectConfig 在 src/config.ts(仓库文件:src/config.ts) 内共用同一读取器,再跑 test/config.test.ts;新增或收紧报文字段与字节限制时修改 src/validate.ts(仓库文件:src/validate.ts) 并同步更新 test/validate.test.ts。更深的设计取舍分别详见来源限制、限流与多令牌轮换机制、报文校验、字节上限与地址归一化与配置解析、过渡别名与健康体检。
test/
| 重要代码 | 功能 | 关键符号 | 调用方 / 使用方 |
|---|---|---|---|
test/handler.test.ts(仓库文件:test/handler.test.ts) | 注入模拟 EMAIL 与 RATE_LIMITER 验证完整请求流水线、鉴权顺序、日志脱敏与健康探针 | makeEnv, call, envelope | pnpm test (vitest run) |
test/config.test.ts(仓库文件:test/config.test.ts) | 验证令牌格式校验、发件域通配边界、开关组合矩阵与健康就绪判据 | env, inspectConfig 用例集 | pnpm test (vitest run) |
test/validate.test.ts(仓库文件:test/validate.test.ts) | 验证邮箱语法、UTF-8 字节边界、收件人总数预算、未知字段与面板报文映射 | catchField, buildStandardMessage, buildPanelMessage | pnpm test (vitest run) |
test/ip.test.ts(仓库文件:test/ip.test.ts) | 验证 IPv4/IPv6 压缩格式、内嵌 v4 映射、非 8 倍数前缀掩码与坏条目报错 | parseIpAddress, parseNetwork, isIpAllowed | pnpm test (vitest run) |
覆盖范围
根目录部署模板 wrangler.jsonc、开发变量模板 .dev.vars.example 与脚本清单 package.json 纳入配置参考边界,用于核对绑定名与本地脚本,不在目录表中单独列为源码目录。
以下目录与文件刻意排除在运行时源码地图之外:docs-site/ 为 VitePress 独立文档站点源码及静态输出;tools/ 为仓库提交与推送离线安全守卫钩子(repo_maintenance_guard.py);dual_push.py 为多远端同步辅助脚本;dist/ 与 .wrangler/ 为本地打包及运行时缓存;.dev.vars 与 wrangler.local.jsonc 为被 Git 忽略的本机真实密钥与私有部署配置,严禁读取或抄入任何文档。
证据状态:除特别标注外,本页基于当前源码已确认。
开发与提交流程验证
改动任意源码模块前,建议先阅读对应的机制说明与约束:
- 修改入口、路由或鉴权逻辑:修改
src/index.ts(保持仅default导出),运行pnpm run check && pnpm test && pnpm run dev验证边缘启动无异常。 - 修改配置字段或健康就绪规则:确保
src/config.ts中loadConfig与inspectConfig共用同一读取逻辑,再跑pnpm test -- test/config.test.ts。 - 修改邮件结构、地址语法或字节上限:更新
src/validate.ts并补充test/validate.test.ts的正反边界断言。 - 本地安全与提交检查:本仓库启用了
tools/repo_maintenance_guard.py提交与推送钩子;提交信息需遵循 Conventional Commits,提交前先核对git status确保.dev.vars与wrangler.local.jsonc未被意外暂存。
下一步可查阅 架构决策与兼容迁移 了解历史别名演进与设计取舍背景。