Google TypeScript 风格指南解析

Google TypeScript 风格指南解析

styleguide 项目地址: https://gitcode.com/gh_mirrors/st/styleguide

前言

TypeScript 作为 JavaScript 的超集，在现代前端开发中扮演着越来越重要的角色。Google 内部有着严格的 TypeScript 编码规范，这份公开的指南正是基于 Google 内部规范调整而来。虽然部分内容可能因 Google 特殊环境而制定，但大部分规范对于外部开发者同样具有参考价值。

基础规范

文件编码与特殊字符

1. UTF-8 编码：所有源文件必须使用 UTF-8 编码
2. 空白字符：仅允许使用 ASCII 水平空格字符(0x20)
3. 转义序列：
   • 优先使用特殊转义序列(\n, \t等)
   • 禁止使用传统八进制转义
4. 非ASCII字符：
   • 可打印字符直接使用 Unicode 字符(如μs)
   • 不可打印字符使用十六进制或 Unicode 转义

// 良好实践
const units = 'μs';  // 直接使用Unicode字符
const output = '\ufeff' + content;  // 不可打印字符使用转义

文件结构组织

标准文件结构

TypeScript 文件应按照以下顺序组织内容：

1. 版权信息(如有)
2. 文件级 JSDoc 注释(使用@fileoverview)
3. 导入语句
4. 文件实现代码

各节之间用一个空行分隔。

导入规范

TypeScript 支持四种导入方式：

| 导入类型 | 示例 | 适用场景 | |----------------|--------------------------|-------------------------| | 模块导入 | import * as foo from | TypeScript 导入 | | 命名导入 | import {Foo} from | TypeScript 导入 | | 默认导入 | import Foo from | 仅用于外部代码要求的情况 | | 副作用导入 | import '...' | 导入有副作用的库 |

// 良好实践
import * as ng from '@angular/core';  // 模块导入
import {Foo} from './foo';            // 命名导入
import Button from 'Button';          // 必要时使用默认导入
import 'jasmine';                     // 副作用导入

路径规范

1. 必须使用路径导入其他 TypeScript 代码
2. 优先使用相对路径(./foo)
3. 避免过多父级引用(../../../)

// 良好实践
import {Symbol1} from 'path/from/root';  // 根目录相对路径
import {Symbol2} from '../parent/file';  // 父级相对路径
import {Symbol3} from './sibling';       // 同级相对路径

导入导出最佳实践

命名空间 vs 命名导入

1. 命名导入：适用于频繁使用或名称清晰的符号
2. 命名空间导入：适用于从大型API导入多个符号

// 不良实践：过长的命名导入
import {Item as TableviewItem, Header as TableviewHeader} from './tableview';

// 良好实践：使用命名空间
import * as tableview from './tableview';
let item: tableview.Item|undefined;

导出规范

1. 必须使用命名导出
2. 禁止使用默认导出
3. 最小化导出API表面

// 良好实践
export const SOME_CONSTANT = ...;
export function someHelpfulFunction() {...}
export class Foo {...}

为什么避免默认导出？

默认导出会导致：

• 缺乏规范名称，维护困难
• 导入时命名不一致
• 可能降低代码可读性

可变导出

1. 禁止直接导出可变绑定(export let)
2. 推荐使用显式getter函数

// 不良实践
export let foo = 3;  // 禁止

// 良好实践
let foo = 3;
export function getFoo() { return foo; }  // 使用getter

类型导入导出

类型导入

使用import type明确表示仅导入类型：

import type {Foo} from './foo';  // 仅导入类型
import {Bar} from './foo';       // 导入值

类型导出

使用export type重新导出类型：

export type {AnInterface} from './foo';

模块与命名空间

1. 必须使用ES6模块语法
2. 禁止使用TypeScript命名空间(namespace)
3. 禁止使用require导入

// 不良实践
namespace Rocket {  // 禁止使用命名空间
  function launch() {...}
}

// 良好实践
// 使用单独文件组织代码

总结

Google 的 TypeScript 风格指南强调：

• 严格的代码组织和结构
• 明确的导入导出规范
• 类型安全的明确表达
• 模块化的代码组织方式

遵循这些规范可以帮助开发者编写出更清晰、更易维护的 TypeScript 代码，特别是在大型项目中。虽然某些规则可能看起来严格，但它们都是 Google 在大型代码库实践中总结出的宝贵经验。

styleguide 项目地址: https://gitcode.com/gh_mirrors/st/styleguide