转转前端开发规范的落地实践

❝

车同轨,书同文,行同伦 - 《礼记·中庸》

转转在早期团队较小的时候，没有太多规范，遇到问题用自己最擅长的方式去解决就行。随着公司发展，团队越来越大，因为没有统一规范而造成的问题也越来越多，例如

• 组件库重复开发，不同小组组件库各有长短，但整体质量有所欠缺

• 不同业务之间，项目无法直接复用，需要大量的开发改造

• 新人上手成本高，每个项目都要深度了解其代码与配置，而不是了解完业务就行

• 一些自动化提效的工具，因为业务项目没有规范，而无法开展

• 等等。。。

基于这些问题，我们在去年上半年，制定了一个转转前端开发规范，经过这大半年的实践，达到了预期的效果。接下来我会具体介绍下转转的前端开发规范，希望能给大家带去一些帮助。之前我们也分享过转转的中后台规范建设，感兴趣的可以 戳这

规范包含哪些内容

我们通过一张规范架构图来直观的了解一下如上图，我们把规范分为五大类

• 开发规范

• 监控规范

• 协作规范

• 流程规范

• 开源规范

其中每个大类下，又包含若干个小分类。本文中，我会详细的介绍下一些重点的规范以及其内容，对于非重点的，待后续我们把文档开源到 Github 上，大家可以自行查阅。

开发规范

本地存储规范

主要包括 localStorage 的使用规范，避免使用存储时会遇到的问题

基础库的使用

使用 localforage 来实现本地存储，该库会优先使用 IndexedDB 以扩大本地存储空间，并采用优雅降级方案，处理了异常情况。

存储溢出问题

localStorage 有存储限制，所以在存储空间用完的情况下，进行 setItem 操作就会报 QuotaExceededError 的错。

事实上，在某些浏览器（如 iOS 11 的 Safari 浏览器）的无痕模式下，localStorage 也是无法读写的，进行 setItem 操作会报一样的 QuotaExceededError 错。

为尽可能避免上述情况，或者在出现时优雅处理，请遵循以下规范：

• 设置过期时间。按如下方式对存储的数据进行封装，并在合适的时机清理过期数据。

const data = {
  data: Object,
  expiredTime: Date.now() + 7 * 24 * 60 * 60 * 1000
}

• 用 try...catch 包裹 setItem 操作

try {
  localStorage.setItem('my_data', JSON.stringify(data))
} catch (e) {
  // 错误处理
}

❝

常见的错误处理方法有：清理过期数据并重试一次；转存至 sessionStorage、自定义的全局对象 myStorage、Vuex 等，但记得在读取时也依次读取。

存储的 key 覆盖问题

key 的命名需要符合如下规范 业务线名_项目名_自定义名称 如：

const PREFIX = 'platform_book_'

try {
  localStorage.setItem(PREFIX + 'my_data', JSON.stringify(data))
} catch (e) {
  // 错误处理
}

注释规范

合理的注释，可以提高代码的可读性和可维护性。

注释的原则

• 如无必要，勿增注释，应当追求「代码自注释」

// bad
// 如果已经准备好数据，就渲染表格
if (data.success && data.result.length > 0) {
  renderTable(data);
}

// good
const isTableDataReady = data.success && data.result.length > 0;
if (isTableDataReady) {
  renderTable(data);
}

• 如有必要，尽量详尽，需要注释的地方应该尽量详尽地去写

注释的规范

遵循统一的风格规范，如一定的空格、空行，以保证注释自身的可读性

• 单行注释使用 //，

注释行的上方需要有一个空行；注释内容和注释符之间需要有一个空格

function getType() {
  console.log('fetching type...');

  // set the default type to 'no type'
  const type = this.type || 'no type';
  return type;
}

• 多行注释使用 /** ... */

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {
  // ...

  return element;
}

• 使用特殊标记注释：如 TODO、FIXME、HACK 等

// TODO: 这里还需要做什么

// FIXME: 这里的实现有问题，以后需要优化

// HACK: 这里的处理是为了兼容低端安卓机的 bug

• 文档类注释，如函数、类、文件、事件