CartoDB Analytics Toolbox Core 开发规范与文档编写指南

项目概述

CartoDB Analytics Toolbox Core 是一个提供地理空间分析功能的工具集，支持多种云平台（BigQuery、Snowflake、Redshift、PostgreSQL等）。本文将详细介绍该项目的开发规范和文档编写标准。

代码提交规范

提交请求格式要求

所有变更必须通过提交请求进行，合并时将采用压缩提交(squash)方式，最终在主分支上形成单个提交记录。

提交请求的命名和描述需要遵循以下规范：

1. 使用约定式提交(Conventional Commits)格式
2. 主要类型包括：
   • feat: 新功能
   • fix: 错误修复
   • docs: 文档更新
   • test: 测试相关
   • chore: 构建过程或辅助工具变更
   • refactor: 代码重构

作用域规范

作用域用于标识影响的云平台和模块，格式如下：

(<云平台>|<模块>)

云平台标识：

• bq: BigQuery
• sf: Snowflake
• rs: Redshift
• pg: PostgreSQL

模块示例：

• h3: H3地理索引模块
• lds: 线性参考系统模块
• quadbin: Quadbin空间索引模块

文档编写指南

文档结构

文档采用Markdown格式，并扩展了元数据和特殊标记功能。标准目录结构如下：

clouds/<云平台>/modules/doc/<模块>/
- _INTRO.md (模块介绍)
- FUNCTION_A.md (函数文档)
- PROCEDURE_B.md (存储过程文档)

模块介绍文档

_INTRO.md文件包含模块的整体介绍，支持YAML格式的元数据头：

---
badges:  # 标识模块状态
- advanced
- beta
order:   # 自定义排序
- PROCEDURE_B
- FUNCTION_A
---

# 模块名称

模块功能描述...

函数文档规范

## 函数名称

```sql:signature
函数名(参数1, 参数2)
```

**描述**

函数功能详细说明。

* `参数1`: `类型` 参数说明。
* `参数2` (可选): `类型` 参数说明。

**返回类型**

`返回值类型`

**示例**

```sql
SELECT 函数调用示例;
-- 预期输出
```

存储过程文档规范

## 存储过程名称

```sql:signature
存储过程名(参数1, 参数2)
```

**描述**

存储过程功能详细说明。

* `参数1`: `类型` 参数说明。
* `参数2` (可选): `类型` 参数说明。

**输出**

描述输出表结构...

**示例**

```sql
CALL 存储过程调用示例;
```

文档辅助元素

1. 提示块：用于显示额外信息或警告

   ````hint:info
   **标题**
   提示内容...
   

2. 内部链接：引用其他函数/存储过程

   [`函数名`](模块名#函数名)
   

3. 图片引用：图片需存放在common/assets/目录

   ![图片描述](图片文件名.png)
   

命名规范要求

BigQuery平台

1. 函数/存储过程调用：

   SELECT `@@BQ_DATASET@@.函数名`();
   CALL `@@BQ_DATASET@@.存储过程名`();
   

2. 函数定义：

   CREATE OR REPLACE FUNCTION `@@BQ_DATASET@@.函数名`
   (
       参数 类型
   )
   

其他平台(Snowflake/Redshift/PostgreSQL)

1. 函数/存储过程调用：

   SELECT @@XX_SCHEMA@@.函数名();
   CALL @@XX_SCHEMA@@.存储过程名();
   

2. 函数定义：

   CREATE OR REPLACE FUNCTION @@XX_SCHEMA@@.函数名
   (
     参数 类型
   )
   RETURNS 返回类型
   

动态依赖声明

当函数名在代码中动态生成时，需要在文件中添加注释声明可能的依赖：

/*
额外依赖:
`@@BQ_DATASET@@.依赖函数`()
*/

平台特定限制

Snowflake平台限制

由于Snowflake原生应用当前限制，存储过程中不能使用临时表(TEMPORARY tables)。解决方案是创建普通表并确保在使用后删除。

最佳实践建议

1. 代码可读性：保持一致的缩进和格式，SQL关键字使用大写
2. 文档完整性：每个函数/存储过程都应提供完整的参数说明和示例
3. 测试覆盖：新增功能应包含相应的测试用例
4. 性能考虑：大数据量操作应考虑分批处理
5. 错误处理：提供清晰的错误提示信息

通过遵循这些规范，可以确保Analytics Toolbox Core项目的代码质量和文档一致性，便于团队协作和后续维护。