AntV L7 地理空间数据可视化项目代码规范指南

AntV L7 地理空间数据可视化项目代码规范指南

L7 🌎 Large-scale WebGL-powered Geospatial Data Visualization analysis engine 项目地址: https://gitcode.com/gh_mirrors/l7/L7

前言

AntV L7 是一个专注于地理空间数据可视化的开源项目，良好的代码规范对于维护大型项目至关重要。本文将详细介绍 L7 项目中的代码风格指南，帮助开发者理解并遵循项目的最佳实践。

类型导入与导出规范

类型导入

在 TypeScript 中，明确区分类型导入和值导入有助于提高代码可读性和性能优化：

// 推荐：使用 type 关键字明确表示导入的是类型
import type { Attribute } from './b';

// 不推荐：混合导入可能导致不必要的依赖
import { Attribute } from './b';

类型导出

在库的入口文件中，类型导出同样需要明确标识：

// src/index.ts
import type { Attribute } from './a';

export type { Attribute };  // 明确导出类型

这种规范有助于构建工具进行更好的 tree-shaking 优化。

类型声明规范

type 与 interface 的选择

L7 项目中优先使用 type 进行类型定义：

// 推荐：使用 type 定义简单类型
type Attribute = {
  color: string;
  size: number;
};

// 不推荐：除非是系统级接口定义
interface IAttribute {
  color: string;
  size: number;
}

interface 适用于需要扩展或实现的系统级接口：

// 适合使用 interface 的场景
interface IBaseMap {
  color: string;
  size: number;
}

class AMap implements IBaseMap {}
class BMap implements IBaseMap {}

文件命名规范

L7 项目采用独特的文件命名约定：

• 多词文件名使用小驼峰加中划线格式：extrude-polyline.ts
• 避免使用下划线或纯小驼峰格式

这种命名方式既保持了可读性，又符合项目统一风格。

变量处理最佳实践

默认值处理

L7 推荐在变量声明时就处理可能的特殊情况：

// 推荐：声明时处理默认值
const { attributes = [] } = options;
// 或
const attributes = options.attributes ?? [];

// 不推荐：在后续代码中处理
const { attributes } = options;
caculateScales(attributes || []);

这种方式使代码意图更清晰，减少后续处理逻辑。

常量命名规范

L7 采用全大写加下划线的常量命名方式：

// 推荐
const DEFAULT_UNIFORM_STYLE = {
  opacity: 1,
  stroke: [1, 0, 0, 1]
};

// 不推荐
const DefaultUniformStyle = {...};

这种命名方式使常量在代码中更易识别。

类成员设计规范

访问控制

L7 严格区分公共和私有成员：

class ALayer {
  private context: Object;  // 私有成员明确标记
  
  private setOptionsAttr() {}  // 私有方法
  
  public _debug: boolean;  // 实验性公共成员
}

• 使用 private 明确标识不对外暴露的成员
• 实验性功能使用 _ 前缀，提醒用户其不稳定性

代码格式规范

空格使用

L7 强调代码的可读性：

// 推荐：import 与代码间有空行
import _ from 'lodash';

const Map = () => {};

// 推荐：注释前后有空格
// 我是注释

class A {
  private a = 1;  // 成员间有空行
  
  public b() {}
}

良好的空格使用习惯使代码结构更清晰。

注释规范

JSDoc 标准注释

L7 采用标准 JSDoc 格式：

/**
 * 计算地图中心点
 * @param bounds - 地理边界坐标
 * @returns 中心点坐标
 */
function getMapCenter(bounds: number[]) {}

class ALayer {
  /**
   * 渲染上下文对象
   * 包含 WebGL 相关状态
   */
  public context: Object;
}

JSDoc 注释不仅提供文档说明，还能与编辑器智能提示集成。

废弃方法标记

对于即将废弃的 API，使用标准标记：

/**
 * @deprecated
 * 请使用 getView().center 替代
 */
function getMapCenter() {}

这种标记方式能被 IDE 识别并给出警告。

结语

遵循 AntV L7 的代码规范不仅能保持代码风格统一，还能提高代码质量和可维护性。这些规范凝聚了项目维护者的经验，值得每一位贡献者学习和遵守。

L7 🌎 Large-scale WebGL-powered Geospatial Data Visualization analysis engine 项目地址: https://gitcode.com/gh_mirrors/l7/L7