❤
npm
Sign UpSign In

@jdthfe/blueprint

0.0.1 • Public • Published

BLUEPRINT

Welcome to the Blueprint documentation!

Getting Started

Blueprint is an way to create specific applications. It offers a modern build setup with no configuration

Quick Start 快速开始

全局安装 blueprint（已经安装的开发者可以跳过此步骤）

jnpm install blueprint -g

在命令行中进入需要创建项目的文件夹（本例为 ~/example)

// 查看可用的模板
// 将会在当前目录下生成 blueprint-list.md
// 包含各个模板的介绍和使用说明

blueprint md

// blueprint <templateName> [projectName] [projectDir]
// templateName 模板名
// projectName 项目名
// projectDir  项目文件夹名称，默认为 project

blueprint init my-app react-0

根据内部上线流程，以及开发模式， ~/example 文件夹下应该存在有 blueprint-common 和 static.init 项目。用以提供公共组件和静态资源。(不同模板可能存在不同情况，具体见 blueprint-list.md)

init 执行之后，将生成如下结构的目录

example
├── blueprint-list.md
├── blueprint-common
├── static.init
├── project
│   ├── my-app
│   ...
...

进入 blueprint-common 中安装依赖并退回到 ~/example 目录

cd blueprint-common && yarn && cd ..

进入项目中且安装依赖

cd project && yarn

启动本地服务器，开发模式 start devSever

yarn s

打包发布 build

yarn b

Structure 目录结构

After creation, your project should look like this:（不同模板生成的目录结构可能有一定差距）

初次使用重点关注 「config.js 配置文件」和 「project 项目源码」即可

my-app
├── package.json
├── README.MD
├── config.js       //  核心配置文件
├── tsconfig.json   //  typescript 配置
│
├── .babelrc.js     //  其他插件配置，如何配置请自行百度文件名
├── .commitlintrc.js
├── .eslintignore
├── .eslintrc,js
├── .gitignore
├── .lintstagedrc.js
├── .prettierignore
├── .prettierrc.js
├── .stylelintrc.js
│
├── build           //  webpack 配置文件
│   ├── build.after.js
│   ├── helpers.js
│   ├── midware.js
│   ├── webpack.config.js
│   ├── webpackDevServer.config.js
│   └── loaders     //  可以在此文件中中定义自己的 loader
│       └── vm-loader
│           ├── lib //  loader loader 依赖置于此，防止代码检查
│           └── index.js
│
├── common          //  公用组件和方法，映射 blueprint-common 文件夹。详见补充说明
│   ├── ...
│   ...
│
├── dist            //  项目输出的目录，用于映射域名对应的静态资源目录。详见补充说明
│   ├── ...
│   ...
│
├── project
│   │
│   ├── api        //  接口相关
│   │   ├── index.tsx           //  接口整合
│   │   ├── html                //  首屏模拟数据
│   │   └── schema              //  接口 mock 和 type
│   │       ├── [apiName.json]
│   │       ├── [apiName.tsx]
│   │       ...
│   ├── src                     //  项目源码
│   │   ├── index.tsx           //  项目入口
│   │   ├── App.tsx
│   │   ├── index.vm            //  模板，可以使用 vm | ejs | html
│   │   ├── images              //  图片
│   │   ├── types               //  类型
│   │   ├── scenes              //  场景，详见补充说明
│   │   ...                     //  可以自由创建需要的文件夹
│   │
│   └── static     //  项目级别的纯静态资源，build 时会完全不改动的粘贴
...

补充说明

对特殊文件夹的补充说明

common

在 yarn s 或 yarn b 过程中，会自动粘此文件夹中的所有文件到 blueprint-common 中。（请勿重名，防止覆盖）

模板中已经配置好了对应的路径依赖，可以通过 import [modulesName] from "@common/*" 的方式引用

注意事项：

  1. 请无视 blueprint-common 中的依赖报错，请勿在 blueprint-common 中安装任何依赖。通用组件所需的依赖和声明文件， 在对应项目中安装即可。

  2. 请勿直接修改 blueprint-common 中的任何文件。如果对应通用组件报错，webpack 的错误提示会指向 blueprint-common。此时应该修改本地 common 中的对应文件，通过框架的自动粘贴覆盖错误代码。

  3. 如果是打包处理过，不需要任何检查的代码。请置于 common-modules 文件夹中。

  4. 提交代码遵循 commitLint 规范

  5. 公共组件开发完成之后可以删除本地 common

目录结构：

blueprint-common
├── package.json
├── .gitignore
├── .commitlintrc.js
├── README.MD
├── common_modules          //  放置编译过的通用组件
├── manifest                //  react dll 相关 mainfest
├── styles                  //  通用属性
├── use                     //  通用 use
├── utiles                  //  通用 utils
...

dist

项目输出的目录，用于映射域名对应的静态资源目录。此例中：

dist 文件对应 mstatic.jd.co.th 域名所映射的，静态资源服务目录 static.init/src/main/webapp

注意事项：

  1. 在 html 中使用 script 或者 link 标签引用的代码才建议放置于此文件夹下。

  2. 请手动拷贝除项目文件夹以外的代码到 static.init 中。此文件夹只用于说明目录结构和存放项目打包代码。且只有项目打包代码会在 build 之后自动被拷贝到 static.init 中。

目录结构：

dist
├── static
│   ├── vendor              //  react dll 相关 vendor
│   ...
│
├── [project]
├── my-app
│   ├── css
│   ├── images
│   ├── js
│   ├── static
│   └── index.html
...

schema

相当于通常项目中的 pages 层级。不同之处在于 schema 鼓励嵌套

假设有如下业务需求：

  1. 订单页，区分为 A 类订单和 B 类订单。

  2. 两种订单页面数据和逻辑有一定差异，但不是完全不同

目录结构容易被设定为如下两种：

  1. 不同订单使用单独页面，订单页的通用逻辑被迫提升到项目级别

    pages
├── commonComponents
│   ├── component1.tsx       //  A 和 B 均用到的通用组件
│   ...
├── Order A
│   ├── Order A.tsx
│   ├── component2.tsx
│   ...
├── Order B
│   ├── Order B.tsx
│   ├── component3.tsx
│   ...
...
    1. 不同订单使用同一页面，各自页面的组件归属不明
    pages
├── Order
│   ├── Order A.tsx
│   ├── Order B.tsx
│   ├── component1.tsx       //  A 和 B 均用到的通用组件
│   ├── component2.tsx
│   ├── component3.tsx
│   ...
...

推荐使用 schema 区分

虽然层级和文件夹数量变多，但业务逻辑更清晰，方便后续维护。可以轻易的增加 Order C，甚至分割出 Order B.1 和 Order B.2

schema
├── Order
│   ├── Order.tsx
│   ├── components
│   ├── schema
│   │   ├── Order A
│   │   │   ├── Order A.tsx
│   │   │   ├── components
│   │   │   ...
│   │   ├── Order B
│   │   │   ├── Order B.tsx
│   │   │   ├── components
│   │   │   ├── schema
│   │   │   │   ├── Order B.1
│   │   │   │   ├── Order B.2
│   │   │   ...

Development Process 开发流程

1. 代码校验

项目预设有严格的格式校验和提交检查。如果运行过程中有任何报错，将无法编译甚至提交。

为了帮助更好的开发，请安装对应插件帮助代码自动格式化。（下列步骤基于 vscode)

  1. 关闭所有格式化相关插件，防止冲突。

  2. 安装并开启 eslint 。建议选择「开启（工作区）」，防止影响其他项目，下同。

  3. 安装并开启 prettier - Code fomatter

  4. 安装并开启 stylelint

  5. 项目最外层新建 .vscode/settings.json 文件，内容如下

    {
  "files.associations": { "*.ts.snap": "html" },
  "editor.formatOnSave": true,
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    { "language": "typescript", "autoFix": true },
    { "language": "typescriptreact", "autoFix": true }
  ],
  "prettier.stylelintIntegration": true
}

  6. 重启 vscode 之后，即可享受自动格式化代码，和部分 bug 自动修复的快感了。

2. 本地启动

如果是 OS 系统需要加 sudo

yarn s

项目会在本地 127.0.0.1:80 端口启动服务。

有任何访问本地的资源请求，将通过以下 4 步

  1. 直接请求，如果失败请求下一步

  2. 映射到项目 dist 文件夹中，删除版本号和 .min 等标识。失败请求下一步

  3. 映射到 static.init/src/main/webapp 文件夹，删除版本号和 .min 等标识。失败请求下一步

  4. 判断请求 host，如果为本地，则返回资源未找到。否则请求 host 原本地址。

因此，可以通过修改 host 映射的方法。替换线上资源为本地文件

例如添加 host： 127.0.0.1 beta-mstatic.jd.co.th

启动本地 my-app 项目

资源 http://beta-mstatic.jd.co.th/my-app/js/index_1_0.js 将被服务器捕获，经过如下处理

  1. 未找到本地请求，下一步

  2. 映射到项目 dist 文件夹中，删除版本号和 .min 等标识，映射成功！

资源 http://beta-mstatic.jd.co.th/static/vendor/react_core.min.js 将被服务器捕获，经过如下处理

  1. 未找到本地请求，下一步

  2. 映射到项目 dist 文件夹中，删除版本号和 .min 等标识，失败，下一步。

  3. 映射到 static.init/src/main/webapp 的 dist 中，删除版本号和 .min 等标识，映射成功！

Tips 如果映射成功，控制台将输出 Development Mode !，在浏览器中观察对应资源的源码，也将增加如下格式的注释。

/**
 * 指向本地文件
 * /Users/name/Files/Work/project/my-app/dist/my-app/js/index.js
 */

3. 项目打包

如果是 OS 系统需要加 sudo

yarn b

在 config.js 中通过修改 version 字段更改版本号，默认为 1.0

项目将在 dist 文件架下，生成对应项目名的打包后代码，并且在 js 和 css 文件之后附带 _1_0 形式的版本号。

打包成功之后，将执行 build/build.after.js 拷贝 dist 文件夹中的项目打包文件到 static.init/src/main/webapp 中

4. 代码提交

代码提交之前会经过如下步骤：

  1. 按照 .lintstagedrc.js 中的规则匹配所有提交的文件。进行对应的 eslint、prettier、stylelint 和 typescript 校验以及自动格式化。通过之后进行下一步。

  2. 项目预制 commitLint，所有提交必须符合规定格式，规则如下。

Commit type Description
build 主要目的是修改项目构建系统(例如 glup，webpack，rollup 的配置等)的提交
ci 主要目的是修改项目继续集成流程(例如 Travis，Jenkins，GitLab CI，Circle 等)的提交
docs 文档更新
feat 新增功能
merge 分支合并 Merge branch ? of ?
fix bug 修复
perf 性能, 体验优化
refactor 重构代码(既没有新增功能，也没有修复 bug)
style 不影响程序逻辑的代码修改(修改空白字符，格式缩进，补全缺失的分号等，没有改变代码逻辑)
test 新增测试用例或是更新现有测试
revert 回滚某个更早之前的提交
chore 不属于以上类型的其他类型

任意步骤失败都将导致代码提交失败

Readme

Keywords

none

Package Sidebar

Install

npm i @jdthfe/blueprint

Repository

coding.jd.com/thfe/blueprint.git

Weekly Downloads

0

Version

0.0.1

License

ISC

Unpacked Size

1.14 MB

Total Files

89

Last publish

Collaborators

  • jdthfe
Try on RunKit
Report malware