从零到贡献Address 本地开发环境搭建与测试体系完整指南【免费下载链接】addressA self-hosted address and synthetic test-profile generator for 27 countries and regions, built from real open-data streets, administrative areas, coordinates, and postcodes. Supports multilingual output, IP-nearby generation, map previews, and API access. 基于真实开放数据的自托管地址与合成测试资料生成器覆盖 27 个国家和地区支持多语言地址、IP 附近生成、地图预览与 API 调用项目地址: https://gitcode.com/gh_mirrors/address4/addressAddress是一个基于真实开放数据的自托管地址与合成测试资料生成器覆盖 27 个国家和地区支持多语言输出、IP 附近生成、地图预览与 API 调用。本文带你从零搭建它的本地开发环境并系统讲解内置的测试体系——从无需真实数据库的单元测试到 Playwright 端到端测试与线上验收脚本让你在提交第一份贡献前对质量门禁心中有数。一、开发环境要求3 个组件就够开始前先确认本地工具链配置非常简单组件版本要求用途Node.js24运行前端Astro React、APIHono与测试PostgreSQL16存放地址池、行政目录与控制数据Python3.10可选仅运行数据同步 ETL 时需要 好消息日常开发不需要任何第三方 API Key。地图平台、Google 地理编码、翻译服务都只用于增强特定国家的数据本地开发可以完全绕开它们。二、克隆仓库并配置环境变量克隆项目国内可直接使用加速地址git clone https://gitcode.com/gh_mirrors/address4/address cd address npm ci项目根目录提供了完整的环境变量模板 .env.example本地开发只需关注其中两项cp .env.example .env # 在 .env 中至少填写数据库连接例如 # POSTGRES_URLpostgresql://address:你的密码127.0.0.1:5432/address其余配置API 端口、同步队列、可选的地图/翻译密钥等保持默认即可。全部可配置项及其含义都能在 .env.example 的注释中找到。三、一键启动本地开发服务数据库迁移和服务启动只需 3 条命令npm run db:migrate # 创建或迁移数据库表结构 npm run dev # 构建 WebUI 并以监听模式运行 API启动后访问http://127.0.0.1:8787即可使用地址生成器管理后台位于/admin/初始密码admin。如果需要前端热更新改为并行运行两条命令Astro 开发服务器运行在 4321 端口并把/api代理到后端npm run dev:api # 终端 1Hono API 监听模式 npm run dev:web # 终端 2Astro 热更新下面是在本地环境生成的美国地址效果右侧地图可点击跳转外部地图应用新数据库初始只有表结构。想在本地真正生成地址按开发文档的做法先导入行政目录再挑一个数据量小的国家如新加坡 SG做增量导入即可整个过程无需访问任何外部数据源密钥。四、读懂测试体系分层设计是核心Address 的测试分为四层由快到慢、由隔离到真实这也是你贡献代码后需要逐层通过的质量门禁。第 1 层单元测试秒级零依赖npm test这是最重要也最轻量的一层基于 pg-mem 内存数据库和小型数据夹具运行完整 Vitest 套件不需要启动真实的 PostgreSQL。tests/ 目录下 90 余个测试文件按职责划分域逻辑generator-determinism.test.ts生成器确定性、postal-grade-format.test.ts邮编格式、china-address.test.ts等数据管线address-pool-v2.test.mjs、address-policy.test.mjs、sync-etl.test.mjs接口与契约api.test.ts、client-context-api.test.ts、translation-recovery.test.mjs第 2 层静态检查与生产构建npm run check # Astro 诊断 TypeScript 全量检查 npm run build # 生产构建 npm run check:public # 检查忽略规则、必需文件与密钥泄露形态第 3 层端到端测试Playwrightnpm run test:admin-e2e # 管理后台控制台端到端流程 npm run test:ui-e2e # WebUI 稳定性与布局测试这两组测试会真实启动浏览器执行页面操作分别对应 tests/admin-console.e2e.mjs 和 tests/ui-reliability.e2e.mjs。只要你改了后台界面这两条命令必须跑通第 4 层线上验收脚本可选部署到可访问环境后还有一组面向真实运行实例的验收脚本例如 scripts/validate-live-api.mjs 逐端点校验 API 契约npm run test:production-live可一次性跑完 API、地址、契约、浏览器四项线上检查。五、提交前检查清单5 条命令对齐 CI项目 CI 在 Ubuntu 与 Windows 双平台上执行的标准检查与本地完全一致提交前按顺序跑完即可npm test npm run check npm run build npm run check:public git diff --checkCI 额外还会用bash -n校验所有 Shell 脚本语法、用python3 -m py_compile编译 server/sync/ 下的 Python 导出器——如果你动到了这两类文件记得本地先验证。六、开始贡献目录结构与协作约定第一次打开源码时对照下面这张速查表找文件会快得多完整版见 docs/DEVELOPMENT.zh-CN.md路径内容src/pages/Astro 路由多语言 WebUI、API 文档、管理后台src/components/admin/后台各页面仪表盘、同步工作区、凭据、安全、快捷地点server/api/公开 API 路由index.ts、数据仓库、外部服务适配server/sync/数据源适配器、ETL、队列与原子发布server/database/PostgreSQL 连接与版本化迁移Schema 见 schema.sqlscripts/目录生成、数据校验、线上验收脚本docs/strategies/每个国家的地址生成策略文档几条值得记住的协作约定改公开 API响应统一为{ data }或{ error }结构需同步更新src/domain/api-contract.ts的 OpenAPI 描述和三语 API 文档如 docs/API.zh-CN.md改数据库新增版本化迁移绝不修改已发布的迁移改国家/数据源国家元数据、地址格式、邮编规则、来源分片、测试与docs/strategies/中的策略文档需同时更新不要提交真实凭据、数据库、日志或含私密数据的截图结语Node 24 PostgreSQL 165 条命令启动分四层测试把关——这就是 Address 从本地运行到贡献代码的完整路径。建议按顺序实践先跑通npm run dev亲眼看到生成结果再挑一个感兴趣的测试文件比如generator-determinism.test.ts读懂它最后带着提交前检查清单发出你的第一份贡献。祝你在 27 个国家与地区的真实街道数据中写出漂亮的第一个 Commit【免费下载链接】addressA self-hosted address and synthetic test-profile generator for 27 countries and regions, built from real open-data streets, administrative areas, coordinates, and postcodes. Supports multilingual output, IP-nearby generation, map previews, and API access. 基于真实开放数据的自托管地址与合成测试资料生成器覆盖 27 个国家和地区支持多语言地址、IP 附近生成、地图预览与 API 调用项目地址: https://gitcode.com/gh_mirrors/address4/address创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
