跳到主要内容

开发规范总览

核心原则​

1. 文本有入口（Text Has Entry Point）​

每一篇文档、每一段说明文本都必须有明确的、可到达的入口路径。

  • 所有文档必须从侧边栏或导航栏可到达 — 不允许存在孤儿页面
  • 每个 API 端点必须在目录树中有索引 — 不能只有 URL 没有导航
  • 所有功能说明必须在产品文档树中有对应位置
  • 跨产品引用使用相对链接，不依赖外部 URL

违反示例（禁止）：

❌ 写了一个 passport/api.md 但侧边栏里没有链接
❌ 新增了 API 但没更新 _sidebar.md
❌ 文档只存在于代码仓库，不在文档站可到达

正确示例：

✅ 新增文档 → 同步更新 sidebar → 导航栏可到达
✅ API 新增 → 更新 API 索引页 → 侧边栏有链接
✅ 每个页面有面包屑导航，可回溯到首页

2. 项目有独立性（Project Has Independence）​

每个项目/产品的文档独立组织，互不依赖，可独立部署和浏览。

  • 每个产品有独立的文档目录（docs/hub/<product>/）
  • 每个产品的文档不引用其他产品的内部路径
  • 跨产品引用通过统一入口页跳转，不深度耦合
  • 每个产品可独立构建和部署 — 不因其他产品变更而受影响

目录结构规范：

docs/
├── hub/
│   ├── std/              # STD 平台 — 独立
│   ├── bi/               # BI 平台 — 独立
│   ├── ec-cloud/         # EC-Cloud — 独立
│   ├── devhub/           # DevHub — 独立
│   │   └── passport/     # Passport — DevHub 子项目，自身独立
│   └── cloud-cms/        # Cloud CMS — 独立
├── standards/            # 开发规范 — 全局共享
└── guide/                # 开发指南 — 全局共享

独立性规则：

  • std/ 的文档不直接 import bi/ 的组件
  • passport/ 的 API 文档不依赖 grant/ 的页面结构
  • 每个产品目录可被单独打包为子站点

文档组织形式​

Google Docs 风格分层​

采用类似 Google Docs 的分层组织形式：

首页（Home）
  ├── 产品矩阵（Product Matrix）
  │     ├── 产品 A
  │     │     ├── 概览（Overview）
  │     │     ├── 快速开始（Quick Start）
  │     │     ├── API 参考（API Reference）
  │     │     │     ├── 认证
  │     │     │     ├── 接口列表
  │     │     │     └── 错误码
  │     │     └── 最佳实践
  │     ├── 产品 B
  │     └── ...
  ├── 开发指南（Guide）
  │     ├── 快速上手
  │     ├── 认证方式
  │     └── 签名规范
  ├── 开发规范（Standards）
  │     ├── 文档入口与项目独立性
  │     ├── API 设计规范
  │     └── 命名规范
  └── 更新日志（Changelog）

搜索增强​

  • 全文搜索 — 标题权重 5x，标题（h2/h3）权重 3x，正文权重 1x
  • 模糊匹配 — 容错 0.2，支持拼写错误
  • 前缀匹配 — 输入关键词前缀即可匹配
  • 多语言搜索 — 每种语言的搜索界面本地化

多语言支持​

语言代码区域
简体中文zh-CN亚太
Englishen-US北美
日本語ja-JP亚太
한국어ko-KR亚太
Deutschde-DE欧盟
Françaisfr-FR欧盟

每种语言：

  • 独立的导航栏和侧边栏
  • 独立的搜索索引
  • URL 前缀隔离（/zh/, /en/, /ja/ 等）
  • 页面内容本地化