1 适用范围
适用于：
- 数据库项目
- 知识库项目
- Web 网站 / Web 应用
- API 服务
- 命令行工具
- 数据采集、清洗、入库和检索系统
- 长期维护的数据产品
例如：
PlantGeneWiki
Gene annotation database
Single-cell data portal
Literature mining platform核心逻辑：
源码主体 → 数据构建脚本 → 配置 → 测试 → 文档 → 部署维护
2 推荐顶层结构
ProjectName/
├── README.md
├── src/
├── scripts/
├── data/
├── docs/
├── tests/
├── config/
├── assets/
└── deploy/如果项目较小，可以先用最小版：
ProjectName/
├── README.md
├── src/
├── scripts/
├── data/
└── docs/3 目录职责
| 目录 | 作用 |
|---|---|
README.md | 项目入口说明、安装、运行、维护方式 |
src/ | 项目主体源码 |
scripts/ | 下载、清洗、建库、索引、部署等命令行脚本 |
data/raw/ | 外部原始数据 |
data/processed/ | 清洗后的中间数据 |
data/database/ | SQLite、DuckDB、索引、构建后的数据库 |
docs/ | 使用说明、开发说明、数据字典、维护文档 |
tests/ | 单元测试、数据一致性测试、接口测试 |
config/ | 配置文件、字段映射、路径配置 |
assets/ | 图片、图标、示例文件、静态资源 |
deploy/ | Docker、服务器部署、定时任务、服务配置 |
4 通用模板
ProjectName/
├── README.md
├── src/
│ └── project_name/
│ ├── __init__.py
│ ├── parser/
│ ├── database/
│ ├── search/
│ ├── api/
│ └── web/
├── scripts/
│ ├── download_sources.py
│ ├── clean_sources.py
│ ├── build_database.py
│ ├── build_index.py
│ └── update_all.py
├── data/
│ ├── raw/
│ ├── processed/
│ └── database/
├── docs/
│ ├── data_sources.md
│ ├── database_schema.md
│ ├── user_guide.md
│ ├── developer_guide.md
│ └── maintenance_log.md
├── tests/
│ ├── test_parser.py
│ ├── test_database.py
│ └── test_api.py
├── config/
│ ├── config.example.yaml
│ └── field_mapping.yaml
├── assets/
│ ├── icons/
│ └── examples/
└── deploy/
├── Dockerfile
├── docker-compose.yml
└── systemd/5 src/、scripts/、utils/ 的边界
| 目录 | 放什么 |
|---|---|
src/ | 可复用、可导入、构成项目主体的源码 |
scripts/ | 一次性或周期性运行的入口脚本 |
utils/ | 可选；跨模块复用的小工具。如果已经有 src/project_name/utils/，顶层可不设 utils/ |
建议：
- 产品型项目优先使用
src/。 - 下载、建库、更新索引用
scripts/。 - 不要把主体源码全塞进
scripts/。
6 数据管理
推荐：
data/
├── raw/
├── processed/
└── database/说明：
data/raw/：外部下载数据，原则上不手动改。data/processed/：清洗后的 TSV/CSV/JSON/Parquet。data/database/：SQLite、DuckDB、FAISS、Elasticsearch dump、搜索索引等。
如果数据很大，可以只保留说明文件：
data/
├── raw/README.md
├── processed/README.md
└── database/README.md在 README 中写明远端路径、下载方式和构建命令。
7 配置管理
推荐：
config/
├── config.example.yaml
├── field_mapping.yaml
└── sources.yaml原则：
- 可公开的默认配置放
config.example.yaml。 - 私密配置不要提交到仓库。
- 数据源、字段映射、数据库表名等尽量配置化。
8 文档管理
推荐：
docs/
├── data_sources.md
├── database_schema.md
├── user_guide.md
├── developer_guide.md
├── deployment.md
└── maintenance_log.md| 文件 | 内容 |
|---|---|
data_sources.md | 数据来源、下载地址、版本、许可证 |
database_schema.md | 表结构、字段含义、主键、索引 |
user_guide.md | 用户如何使用 |
developer_guide.md | 开发者如何安装、运行、扩展 |
deployment.md | 部署方式 |
maintenance_log.md | 更新记录和维护记录 |
9 测试管理
产品型项目建议保留 tests/。
常见测试：
- parser 是否能解析示例文件
- 数据库表是否存在
- 主键是否唯一
- API 是否返回预期字段
- 构建脚本是否能跑通小样例
示例：
tests/
├── fixtures/
│ └── example_gene_annotation.tsv
├── test_parser.py
├── test_database.py
└── test_api.py10 命名规范
脚本命名：
动作_对象.py例如：
download_sources.py
parse_gene_annotations.py
build_database.py
build_search_index.py
update_all.py模块命名：
小写字母 + 下划线例如：
gene_parser.py
database_loader.py
search_index.py11 README 建议结构
# ProjectName
## Background
## Features
## Data sources
## Directory structure
## Installation
## Usage
## Build database
## Run tests
## Deployment
## Maintenance
## License
评论