Blockly 开发规范文档：代码风格与最佳实践指南

Blockly 开发规范文档：代码风格与最佳实践指南

【免费下载链接】blockly The web-based visual programming editor. 项目地址: https://gitcode.com/gh_mirrors/bl/blockly

Blockly 作为一款可视化编程编辑器框架，其代码质量直接影响开发者体验和项目可维护性。本文档基于 eslint.config.mjs 和项目实践，系统梳理代码风格规范与工程化最佳实践，帮助开发团队构建一致、高效的代码库。

代码风格基础规范

命名约定

Blockly 采用 Google 风格指南并针对项目特性优化，核心命名规则如下：

• 变量/函数：使用 camelCase 命名法，允许以下特殊前缀：
  • opt_：标记可选参数（如 opt_callback）
  • testOnly_：仅测试环境使用的函数（如 testOnly_validateBlock）
• 类/接口：采用 PascalCase 命名（如 BlockSvg、WorkspaceComment）
• 常量：使用 UPPER_SNAKE_CASE（如 MAX_BLOCK_DEPTH）

相关配置：eslint.config.mjs#L27-L33

代码格式化

• 缩进：使用 2 空格缩进（禁用制表符）
• 行宽：单行代码不超过 80 字符
• 分号：强制使用分号结尾
• 空格规则：
  • 函数声明括号前需空格（function test () {}）
  • 注释起始符后必须空格（// 正确注释）

文件组织规范

源码文件需遵循以下目录结构：

core/                # 核心功能模块
├── block.ts         # 基础块定义
├── workspace.ts     # 工作区管理
├── events/          # 事件系统
└── renderers/       # 渲染器实现
blocks/              # 标准块定义
generators/          # 代码生成器
tests/               # 测试代码

TypeScript 开发规范

类型定义

• 禁止隐式 any：除历史代码外，新代码需明确类型（临时例外：eslint.config.mjs#L89）
• 接口命名：使用名词短语（如 IBlockDragStrategy）
• 空对象类型：允许用于声明合并（eslint.config.mjs#L91）

类设计

// 推荐模式：明确访问修饰符
export class BlockSvg {
  private id_: string;
  protected renderManager: RenderManager;
  
  constructor(id: string) {
    this.id_ = id;
  }
  
  /**
   * 获取块唯一标识
   * @returns 16位字符串ID
   */
  getId(): string {
    return this.id_;
  }
}

JSDoc 文档规范

基础格式

所有导出 API 必须包含 JSDoc 注释：

/**
 * 创建新的变量块
 * @param {string} name - 变量名称
 * @param {string} type - 数据类型（number|string|boolean）
 * @returns {Block} 新创建的块实例
 */
function createVariableBlock(name, type) {
  // 实现代码
}

特殊标签

Blockly 扩展标签支持：

• @sealed：标记不可继承类
• @typeParam：泛型类型说明
• @remarks：详细功能描述

配置文件：eslint.config.mjs#L110-L116

工程化最佳实践

代码检查工作流

1. 提交前检查：配置 pre-commit 钩子执行 npm run lint
2. CI 集成：在 GitHub Actions 中添加 lint 任务
3. 自动修复：使用 eslint --fix 处理可自动修复的问题

测试规范

• 单元测试：使用 Mocha 框架，测试文件放在 tests/mocha/ 目录
• 测试命名：测试函数以 test 开头（如 testBlockSerialization）
• 断言库：使用 Chai 的 expect 风格（expect(result).to.equal(true)）

测试配置：eslint.config.mjs#L203-L228

版本控制

• 提交信息：遵循 Angular 规范（feat: 添加拖拽锁定功能）
• 分支策略：
  • develop：开发分支（README.md#branches）
  • master：稳定发布分支
  • 功能分支：从 develop 创建，命名格式 feature/xxx

可视化资源使用

Blockly 提供多种内置图标资源，推荐优先使用项目内置素材：

资源目录：media/

常见问题与解决方案

ESLint 规则冲突

Q：如何处理 camelcase 规则与遗留代码的冲突？
A：使用 /* eslint-disable camelcase */ 局部禁用，并在重构计划中标记。

类型声明合并

Q：如何扩展第三方库类型？
A：使用 TypeScript 声明合并：

declare module 'blockly' {
  interface Block {
    newFeature: () => void;
  }
}

附录：参考资源

• 官方文档：README.md
• 核心模块：core/
• 代码生成器：generators/
• 贡献指南：CONTRIBUTING.md（需从项目根目录获取）

通过遵循以上规范，可显著提升代码一致性和团队协作效率。定期查阅 eslint.config.mjs 获取最新规则更新。

【免费下载链接】blockly The web-based visual programming editor. 项目地址: https://gitcode.com/gh_mirrors/bl/blockly