项目创建

  1. 统一使用公司脚手架创建
  2. C端用户使用spa模板，B端用户使用kms模板

命名规范

项目命名规范

  1. 名字统一使用单词或单词缩写命名，缩写名称需要在描述上写明全英文单词
  2. 多个单词之间使用英文连字符“-”连接
  3. 后端项目使用“-server”结尾，前端项目使用”-front“结尾

组件命名规范

  1. 所有页面都用单独的文件夹承载，内部独立的models进行管理
  2. model文件驼峰式，如addPrice.model.js
  3. router集中式管理，放在src根目录下的routes下，可以拆分不同模块的文件夹
  4. 统一输出标准的react component的文件以jsx后缀
  5. react组件名要带有业务属性，如PriceList、 PriceDetail等。禁止直接使用通用名，如：From、List等命名。

  6. 统一是用less，文件命名：style.model.less

    文件目录规范

    image.png

    注释规范

  7. 【强制】TypeScript接口、JS函数、Util的注释必须使用 JSdoc 规范，使用 /* 内容 / 格式，写名功能、参数、return及TODO。可用VScode插件生成标准格式

  8. 【强制】API接口配置需要有详细的接口说明及Yapi文档地址。
  9. 【强制】所有组件、hook、models、等JS及JSX文件都必须添加创建者和创建日期。可用VScode插件生成标准格式
  10. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用 // 注释。
  11. 【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。
  12. 【推荐】与其用半吊子英文来注释，不如用中文注释说清楚。专有名词与关键字保持英文原文即可。

示例

1.文件头部注释

  1. /*
  2.  * @Author: guojianli02@xxx.com
  3.  * @Date: 2022-04-02 14:54:38
  4.  * @LastEditors: guojianli02@xxx.com
  5.  * @LastEditTime: 2022-04-02 14:54:38
  6.  * @Description: 这是一个测试文件
  7.  */

2.函数注释

  1. /**
  2.  * @description: 测试函数
  3.  * @param {string} name 姓名
  4.  * @param {number} age  年龄
  5.  * @returns {string} 返回一段描述 
  6.  */
  7. function test(name, age) {
  8.   const str = `my name is ${name}, I am ${age} years old`
  9.   return str
  10. }

3.API类注释

  1. /**
  2.  * @description xxx
  3.  * @param {string} contentId 直播contentId
  4.  * @param {string} params.uid 用户ID
  5.  * @see https://yapi.xxx.com/project/2327/interface/api/21616 接口文档地址
  6.  * @returns {Promise<UserLogoutData>}
  7.  */
  8. export const getEveluateStatus = ({ uid, contentId }) => {
  9.   return camelCaseResponse(
  10.     request.get(
  11.       `${configService.getNpsApiServiceBasePath()}/api/nps/course/comment/status`,
  12.       { content_id: contentId, uid }
  13.     )
  14.   )
  15. }

4.interface注释

  1. export interface IMessageUpdate {
  2.   /**
  3.    * id
  4.    */
  5.   id: number;
  6.   /**
  7.    * 角色
  8.    */
  9.   role: string;
  10.   /**
  11.    * 时间
  12.    */
  13.   time: number;
  14.   /**
  15.    * 聊天消息
  16.    */
  17.   content: string;
  18. }

5.函数内部单行注释

  1. 方法内部单行注释，在被注释语句上方另起一行，使用 // 注释。
  2. /**
  3.  * @description: 测试函数
  4.  * @param {string} xxx 
  5.  * @returns {string} 返回data
  6.  */
  7. function getData(xxx) {
  8.     // data的用途
  9.   const data = xxx;
  10.   return data;
  11. }

注释插件

1.安装

在插件商店抖索koroFileHeader，安装。
image.png

2.设置settings

下面的规则可以自行设置

  1. // 头部注释
  2.     "fileheader.customMade": {
  4.         "Author": "朽木白", // 创建文件的作者或者邮箱
  5.         "Date": "Do not edit", // 文件创建时间(不变)
  6.         "LastEditors": "xxx@xxx.com", // 文件最后编辑者
  7.         "LastEditTime": "Do not edit", // 文件最后编辑时间
  8.         // 插件会自动将光标移动到Description选项中 方便输入 Description字段可以在specialOptions更改
  9.         "Description": "" // 介绍文件的作用、文件的入参、出参。
  10.     },
  11.     // 函数注释
  12.     "fileheader.cursorMode": {
  13.         "description": "", // 函数注释生成之后，光标移动到这里
  14.         "param": "", // param 开启函数参数自动提取 需要将光标放在函数行或者函数上方的空白行
  15.         "returns": "", // 函数返回值
  16.     },
  17.     "fileheader.configObj": {
  18.         "autoAdd": false // 检测文件没有头部注释，自动添加文件头部注释
  19.     }

3.快捷键

  1. 文件头部注释快捷键：window：ctrl+win+i,mac：ctrl+cmd+i
  2. 函数注释快捷键：window：ctrl+win+t,mac：ctrl+cmd+t