一、背景
为了统一团队的研发方式，对团队代码资产的目录结构做最佳实践的统一规范，降低对于各类代码资产的理解、维护成本，并方便统一的构建和管理。
二、规范内容
命名原则
- 命名尽量简洁，有习惯缩写的单词用缩写的形式
- 目录和文件名称统一使用小写加连字符（(kebab-case)）
规范概述
| ### 示例文件树代码块JavaScript
.
├── src // 源代码
│ ├── index.js // 【卡控文件】在这里导出所有组件
│ ├── components // 所有组件的源码
│ │ └── button // 组件文件夹
│ │ ├── index.js // 【卡控文件】构建入口
│ │ ├── index.vue // 【卡控文件&注释】解析入口
│ │ ├── description.js // 【卡控文件&内容】组件额外信息
│ │ ├── assets // 组件静态资源
│ │ │ └── button-icon.ico
│ │ ├── examples // 示例，将被用于文档与本地调试
│ │ │ └── button-preview.vue // 【卡控文件】
│ │ ├── styles // 组件样式
│ │ │ └── button.css
│ │ └── __tests__ // 测试用例，默认会被运行
│ │ └── button.spec.js // 【卡控文件】
│ ├── api // 公共接口
│ │ └── api-test.js
│ ├── assets // 公共静态资源
│ │ └── asd.png
│ ├── lib // 公共工具函数
│ │ ├── axios.js
│ │ └── http.js
│ ├── mixins // 公共mixin
│ │ └── mixin-a.js
│ ├── plugin // 插件
│ │ └── test-plugin.js
│ └── styles // 公共样式
│ └── common.css
├── docs // 存放额外的文档页
│ ├── get-started.md
├── entry // 本地调试入口，引用examples中定义的示例
│ ├── app.vue
│ └── main.js
├── build // 构建产物【需确定是否需要构建，直接引用源码】
│ └── button.common.js
├── tests // 测试相关
│ ├── compatibility // 兼容性测试相关
│ └── unit // 单元测试相关
│ │ └── mixin-a.js
├── bin // 构建脚本
│ ├── build-bundle.js
│ └── build.js
├── config // 工程配置
│ └── config.common.js
├── types // ts说明文件
│ ├── button.d.ts
├── package.json
├── CHANGELOG.md
├── README.md
├── jest.config.js
├── vue.config.js
├── yarn.lock
├── .commitlintrc.js
├── .cz-configrc.js
├── .editorconfig
├── .eslintignore
├── .eslintrc.js
├── .gitignore
├── .npmignore
├── .npmrc
├── .stylelintignore
├── .stylelintrc
规范概述
-
基本结构
-
根目录下必须有 src/components/，可创建 tests/, entry/, build/, bin/, config/, types/ 这些文件夹。
-
根目录必须包含的文件：
- 依赖管理：package.json、yarn.lock。
- 工程说明：README.md。
- 变更历史：CHANGELOG.md。
- 代码书写规范：.commitlintrc.js、.cz-configrc.js、.editorconfig、.eslintrc.js、.stylelintrc。
-
-
组件相关
- src/components 下的组件会被收录，组件库工程的资产发现不支持嵌套组件，仅会收集匹配 src/components/*/index.vue 规则的组件（即第一层组件）到资产管理平台。
-
测试相关：卡控测试用例
- src/components/*/ tests 用于存放各组件的测试用例
- 每个组件必须包含至少一个 *.spec.js 的单元测试用例文件。脚手架默认逻辑会运行以上规则的测试用例。
- 外层 tests/ 文件夹下可存放其他关于测试的文件，如测试报告，或者其他的测试方式需要的文件。
-
调试相关
-
建议的调试方式：在 entry/ 下编写相关代码：
- entry/ 下为一个简单的单页应用，默认挂载了路由，可以引入src/components/*/examples/ 中定义的示例，即可以进行本地的调试。
-
每个组件必须包含至少一个 src/components//examples/.vue 的示例文件，用于在调试页面中引入。
-
entry/main.js 示例，后续会提供类似约定式路由的能力
-
-
文档相关：文档通过组合多个来源的信息，自动生成，在每次发包时部署。
- 描述信息：src/components/*/description.js：
module.exports = {
importName: "", // 组件的引用名
title: "", // 组件中文名
description: "", // 组件的描述
screenshot: [], // 组件截图，图片链接数组
};
-
不同于业务工程，组件库中将会卡控该文件内容，并确保每个字段的信息完善。同时该文件的内容会被结构化存储，并用于资产的检索（关键字+图片）。
-
API信息
-
通过注释规范，研发框架能够解析出组件的API信息，在对标中提到，将会卡控props, slots, events的注释内容，确保组件信息的完整。
-
组件预览
-
预览信息会自动引用 src/components/*/examples/ 下的组件示例，展示在文档中，并会注入示例文件的代码。需要确保 examples/ 下的vue文件能够直接运行
-
文档生成
-
生成的markdown文件通过vuepress渲染为页面，示例。
-
额外的文档：如「快速上手」等可以在docs中定义.md文件，在文档构建时会一并加入。
-
其他的规范与业务工程的类似
目录规范细则
规范关键词：MUST必须、CAN可以、SHOULD应该、RECOMMENDED建议
组件工程根目录
-
必须MUST包含 src/。
-
可以CAN包含 entry/、tests/、build/、types/、bin/、docs/、config/、public/ 中的若干个。
- src/ 下存放业务源码。
- entry/ 下存放用于本地调试的代码。
- docs/ 下存放文档相关文件。
- tests/ 下存放测试相关代码。
- build/ 下存放构建产物。
- types/ 下存放ts声明文件。
- bin/ 下存放执行脚本文件。
- config/ 下存放配置相关文件。
- public/ 下存放本地调试页面的模板。plug
-
必须MUST包含 index.js，通常用于导出所有组件，作为构建入口。
-
必须MUST包含package.json、README.md、yarn.lock、.commitlintrc.js、.cz-configrc.js、.editorconfig、.eslintrc.js、.stylelintrc、CHANGELOG.md 来完成依赖管理、工程说明、依赖版本锁定、代码书写规范以及变更历史的约束。
-
根目录下还应该SHOULD包含.eslintignore、.gitignore、.stylelintignore、.npmrc、vue.config.js、tsconfig.json、.env.*等配置文件。
各子目录
-
源码相关应放在 src/ 目录下
-
必须MUST包含 components/。
-
组件应该SHOULD放在 components/ 下面，必须MUST创建组件文件夹进行放置。需要对外开放使用的组件应该SHOULD放在 components/第一级目录下。PS：资产解析插件仅解析 ./src/components/ 下的第一层组件并上报到资产管理平台。
对每个组件文件夹 src/components/** ：
-
必须MUST有 index.vue 文件作为组件的解析入口。
- 必须MUST遵循注释规范，props, events, slot必须在注释中说明
-
必须MUST有 index.js 文件作为构建入口。
-
组件根目录下的其他文件必须MUST是 .vue、.js 类型。
-
必须MUST包含 description.js，且各字段必须MUST完善。
-
代码块
JavaScript
-
-
-
// description.js
module.exports = {
importName: "", // 组件的引用名
title: "", // 组件中文名
description: "", // 组件的描述
screenshot: [], // 组件截图，图片链接数组，可在此上传获得链接
};
-
必须MUST包含 tests/，存放组件的测试用例。
-
必须MUST包含 examples/，存放组件的示例代码，用于调试以及文档生成。
- examples/ 下的.vue组件建议RECOMMENDED导出完整的页面组件，在 entry/ 中可以不需要参数引用，同时资产管理平台将在自动生成的文档中展示该示例以及对应的代码
-
可以CAN包含 styles/、assets/、api/、mixins/、lib/、components/ 这几个文件夹，除此之外不可以包含其他文件夹。
- styles/：存放该组件的样式文件，不过更推荐内联到.vue文件中。
- assets/：存量只属于该组件静态文件如图片。
- api/：存放只属于该组件的api文件。
- mixins/：只属于该组件的“混入”逻辑。
- lib/：只属于该组件的工具函数。
- components/：组件会使用到的其他子组件，不应对外开放。
-
可以CAN包含 lib/、api/、plugins/、assets/、styles/、mixins/ 中的若干个。
-
公共工具函数应该SHOULD放在 lib/ 下面。
-
公共后台接口逻辑应该SHOULD放在 api/ 下面。
-
公共插件、过滤器（Vue.filter）、自定义指令（Vue.directive）应该SHOULD放在 plugins/ 下面。
- 公共插件推荐RECOMMENDED实现Vue.use(plugin)，页面只需引入即可使用。
-
公共静态资源如图片应该SHOULD放在 assets/ 下面。
- assets下如需按照静态资源类型存放可按照 imgs、fronts、js、css 等进行划分。
-
公共动态样式文件应该SHOULD放在 styles/ 下面。
-
组件公共的“混入”代码应该SHOULD放在 mixins/ 下。
- 目录以及子目录下只可以包含MUST*.js 文件。
-
测试相关的文件应该SHOULD放在 tests/ 下。
-
各组件的测试用例已在组件目录中定义，该文件夹用于存放测试的配置文件、测试结果等信息。
-
单元测试，e2e测试，ssr兼容测试等都可以放在这个文件夹。
-
文档相关的文件应该SHOULD放在 docs/ 下。
-
本地调试相关的文件应该SHOULD放在 entry/ 下。
-
构建产物应该SHOULD放在 lib/ 下。
-
可执行脚本应该SHOULD放在 bin/ 下。
-
ts声明文件应该SHOULD放在 types/ 下。
-
工程相关的配置文件应该SHOULD放在 config/ 下。
-
本地调试用的html模板等应该SHOULD放在 public/ 下。
