Zander Hsueh

K8S 中使用非 root 用户运行前端项目

xuezenghui6@gmail.com (Zander Hsueh) — Sun, 07 Apr 2024 13:47:50 +0800

Kubernetes 中的镜像一般根据项目类型进行构建，前端项目的最佳实践是将 Dockerfile、项目的 Nginx 配置文件与代码文件统一管理在 Git 仓库中，Dockerfile 中使用的镜像若为 Nginx 的基本镜像 nginx 则不符合安全性的要求，因为该镜像监听的端口是 80，而 0-1024 为特权端口，只能使用 root 用户来运行。换句话说，你跑在 k8s 中的前端项目的 Pod 也将以 root 用户运行，Pen-test 给出的不安全评级为 Medium：

A number of containers were running as the ‘root’ user (this is the default setting) which could make it easier for an attacker with access to the containers to break out to the underlying host. The following was identified:

1
2


$ id
uid=0(root) gid=0(root) groups=0(root)

解决方案分为两步：

使用 Nginx 的非特权镜像 nginx-unprivileged 作为前端项目的基础镜像
部署到 K8s 时设置 Pod 的安全上下文 runAsNonRoot 配置

更换 Nginx 基础镜像

从 nginx-unprivileged 镜像的文档和源代码中可以得到以下几个重要信息：

监听的端口由 80 更换为 8080
运行容器的新用户为 nginx
nginx 用户的 UID 为 101

更新 Dockerfile 文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


FROM nginxinc/nginx-unprivileged:latest

# 替换项目中的 Nginx 配置文件
USER root
ADD ./dist /usr/share/nginx/html
RUN rm -rf /etc/nginx/conf.d/default.conf
COPY ./nginx.conf /etc/nginx/conf.d/default.conf
RUN chmod -R 777 /etc/nginx/
RUN id nginx
USER nginx

CMD ["nginx", "-g", "daemon off;"]

由于更换了新的端口，修改旧的 Nginx 配置文件监听端口为 8080：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


server {
listen 8080;
root /usr/share/nginx/html;
location / {
try_files $uri $uri/ /index.html;
}
location ~* ^.+\.(ico|gif|jpg|jpeg|png|js|css|svg)$ {
access_log off;
add_header Cache-Control "immutable";
expires 1y;
}
location ~* ^.+\.(otf)$ {
add_header Cache-Control "immutable";
access_log off;
expires 1y;
}
}

修改 K8s 配置

安全上下文（Security Context）有两个层级：Pod 层级和 Container 层级。Pod 层级的安全上下文会应用到 Pod 中所有的 Container，Container 层级的安全上下文只影响设置的 Container，且如果 Pod 层级上同时也设置了，则会以 Container 层级的设置为准，重写 Pod 层级的设置。

所以要根据项目的情况来选择，但常见情况下前端项目只有一个 Container，设置在两个层级没有差别，此处以设置在 Pod 层级为例，设置 runAsNonRoot 为 true，runAsUser 为上面得到的 nginx 用户 UID 101：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


apiVersion: apps/v1
kind: Deployment
metadata:
 name: frontend-demo
spec:
 securityContext:
 runAsNonRoot: true
 runAsUser: 101
 containers:
 - name: frontend-demo
 image: frontend-demo-image

同时将端口相关的配置由 80 改为 8080，如 containerPort 、探针检测的端口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


 ...
 containers:
 - name: frontend-demo
 ports:
 - containerPort: 8080
 name: 8080tcp
 protocol: TCP
 livenessProbe:
 failureThreshold: 3
 httpGet:
 path: /index.html
 port: 8080
 scheme: HTTP
 initialDelaySeconds: 90
 periodSeconds: 30
 successThreshold: 1
 timeoutSeconds: 2
 startupProbe:
 failureThreshold: 30
 httpGet:
 path: /index.html
 port: 8080
 scheme: HTTP
 initialDelaySeconds: 60
 periodSeconds: 5
 successThreshold: 1
 timeoutSeconds: 2

以及作为服务发现的 Service 的端口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


apiVersion: v1
kind: Service
metadata:
 name: frontend-demo-service
spec:
 ports:
 - nodePort: 32329
 port: 8946
 protocol: TCP
 targetPort: 8080

验证

在 Container 中执行 id 命令：

1
2


$ id
uid=101(nginx) gid=101(nginx) groups=101(nginx)

得解。

❤️Ten Years

xuezenghui6@gmail.com (Zander Hsueh) — Mon, 20 Nov 2023 01:12:00 +0800

暮雪夜，友朋间，华年里伴歌酌庆酒。

花语酿，膝下金，热血时洒泪惘白首。

十年青葱，

学堂郎朗，有全然不顾留满园懵懂与念想，

骊山相隔，怀自由激烈奔赴两地相见芬芳。

长江千里，虽难忍小别但见未来心意两厢。

今，

少年沉性薄发可独当一面，

萧娘爱人有知万事皆轻盈。

问十载一瞬，何顾何愿？

顾，瓶颈之期，予她予己难达所望。

愿，廿年之日，不悔不惑静心还向。

Linux 自动压缩 log 脚本

xuezenghui6@gmail.com (Zander Hsueh) — Fri, 03 Jun 2022 18:31:22 +0800

线上应用一般会产生大量日志文件，如 Java 应用不同级别的 log、Nginx 的 access.log 和 error.log，日积月累会极其占用磁盘空间，因此需要定期对 log 进行压缩、备份和删除，本文先分享我们的应用日志和 Nginx 日志的压缩策略和方式。

编写 Bash Shell 压缩脚本

先了解两个概念：

Bash Shell：Unix、Linux 系统的一种脚本文件，是大多数 Linux 发行版中的默认 Shell，以 .sh 结尾，使用 $ sh name.sh 命令执行。
.tar.gz 格式文件：.tar 为多个文件归档为一个文件的格式，会保留文件的元数据信息，.gz 为将单个文件使用 Gzip 压缩后的格式。通过 Tar + Gzip 压缩比 Zip 压缩效率高且节省空间更多，环境上也更为兼容。

Java APP log Bash Shell

为了更好的排查 log，我们将 Micro Service 架构下 Java 应用的 log 组织为了如下示例结构（应用中使用 Logback 工具）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


log
├── micro-service1
│   ├── 2022-06-01
│   │   ├── error.micro-service1-pod-id.log
│   │   └── info.micro-service1-pod-id.log
│   ├── 2022-06-02
│   │   ├── error.micro-service1-pod-id.log
│   │   └── info.micro-service1-pod-id.log
│   └── 2022-06-03
│   ├── error.micro-service1-pod-id.log
│   └── info.micro-service1-pod-id.log
└── micro-service2
├── 2022-06-01
│   ├── error.micro-service1-pod-id.log
│   └── info.micro-service1-pod-id.log
├── 2022-06-02
│   ├── error.micro-service1-pod-id.log
│   └── info.micro-service1-pod-id.log
└── 2022-06-03
├── error.micro-service1-pod-id.log
└── info.micro-service1-pod-id.log

Bash Shell 也以此结构为基准进行编写：

1. 新建 Bash Shell 文件 java-log-compress.sh，指定解释器路径，定义初始变量

1
2
3
4
5
6


#!/bin/bash

# log 文件目录绝对路径
base_dir="/var/log"
# 当前日期
date="$(date "+%Y-%m-%d")"

2. 循环 Micro Service 文件列表

1
2
3
4
5
6
7
8
9


# 进入 log 目录
cd $base_dir
# 将以 micro-service 开头的所有目录名存入变量
services=$(ls -f micro-service*/)
# 循环目录名 list
for service in $services
do
echo "service: $service"
done

使用变量时 {} 符号可选，与字符串拼接时必须加，否则会识别错误。

3. 循环 log 日期列表

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


for service in $services
do
echo "service: $service"
# 进入 log 目录
++ cd $base_dir
# 判断是否存在 micro service 目录
++ if [ -d $service ]; then
# 进入 micro service 目录
++ cd $service
# 将当前路径存入变量
++ service_path=$(pwd)
++ echo "start compress"
# 将所有日期目录名存入变量
++ date_dirs=$(ls -d *)
# 循环日期目录 list
++ for dir in $date_dirs
++ do
++ echo "date_dir: $dir"
++ done
++ fi
done

在 service 目录里重新 cd $base_dir 而不直接 cd $service 的目的是防止下次循环在该 service 目录直接去 cd 下一个 service 目录导致报错。

此时执行 sh java-log-compress.sh 的打印：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


service: micro-service1/
start compress
date_dir: 2022-06-01
date_dir: 2022-06-02
date_dir: 2022-06-03
service: micro-service2/
start compress
date_dir: 2022-06-01
date_dir: 2022-06-02
date_dir: 2022-06-03

4. 执行压缩

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


 for date_dir in $date_dirs
do
echo "date_dir: $date_dir"
# 判断该日期是否为今天
++ if [ $date_dir != $date ]; then
++ echo "run tar -zcvf ${date_dir}.tar.gz $date_dir"
# 将日期目录压缩为 .tar.gz 文佳
++ tar -zcvf ${date_dir}.tar.gz $date_dir
fi
done

此时执行 sh java-log-compress.sh 后的目录结构如下，..日期不为今天..的 log 目录（存量数据）都被压缩完成，可使用 tar -zxvf *.tar.gz 解压查看 log 内容是否正常。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


log
├── micro-service1
│ ├── 2022-06-01
│ │ ├── error.micro-service1-pod-id.log
│ │ └── info.micro-service1-pod-id.log
│ ├── 2022-06-01.tar.gz
│ ├── 2022-06-02
│ │ ├── error.micro-service1-pod-id.log
│ │ └── info.micro-service1-pod-id.log
│ ├── 2022-06-02.tar.gz
│ └── 2022-06-03
│ ├── error.micro-service1-pod-id.log
│ └── info.micro-service1-pod-id.log
└── micro-service2
├── 2022-06-01
│ ├── error.micro-service1-pod-id.log
│ └── info.micro-service1-pod-id.log
├── 2022-06-01.tar.gz
├── 2022-06-02
│ ├── error.micro-service1-pod-id.log
│ └── info.micro-service1-pod-id.log
├── 2022-06-02.tar.gz
└── 2022-06-03
├── error.micro-service1-pod-id.log
└── info.micro-service1-pod-id.log

5. 删除已被压缩的 log 文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


 cd $service
service_path=$(pwd)
echo "start compress"
date_dirs=$(ls -d *)
for date_dir in $date_dirs
do
echo "date_dir: $date_dir"
if [ $date_dir != $date ]; then
echo "run tar -zcvf ${date_dir}.tar.gz $date_dir"
tar -zcvf ${date_dir}.tar.gz $date_dir
# 判断是否存在压缩完成的文件
++ if [ -f ${service_path}/${date_dir}.tar.gz ]; then
# 删除源文件夹
++ rm -rf ${service_path}/${date_dir}
++ fi
fi
done

执行 sh java-log-compress.sh 后的目录结构如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


log
├── micro-service1
│   ├── 2022-06-01.tar.gz
│   ├── 2022-06-02.tar.gz
│   └── 2022-06-03
│   ├── error.micro-service1-pod-id.log
│   └── info.micro-service1-pod-id.log
└── micro-service2
├── 2022-06-01.tar.gz
├── 2022-06-02.tar.gz
└── 2022-06-03
├── error.micro-service1-pod-id.log
└── info.micro-service1-pod-id.log

完整的 Bash Shell：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


#!/bin/bash

base_dir="/var/log"
date="$(date "+%Y-%m-%d")"
cd $base_dir
services=$(ls -d micro-service*/)
for service in $services
do
echo "service: $service"
cd $base_dir
if [ -d $service ]; then
cd $service
service_path=$(pwd)
echo "start compress"
date_dirs=$(ls -d *)
for date_dir in $date_dirs
do
echo "date_dir: $date_dir"
if [ $date_dir != $date ]; then
echo "run tar -zcvf ${date_dir}.tar.gz $date_dir"
tar -zcvf ${date_dir}.tar.gz $date_dir
if [ -f ${service_path}/${date_dir}.tar.gz ]; then
rm -rf ${service_path}/${date_dir}
fi
fi
done
fi
done

Nginx log Bash Shell

Nginx 的 access.log 和 error.log 默认为单文件，为方便日常排查问题和节省磁盘空间同样推荐使用 Bash 脚本切割和压缩 log 文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


#!bin/bash

# 目标目录
logs_path="/usr/local/nginx/logs/history"
# 当前 log 目标
current_logs_path="/usr/local/nginx/logs"
# 昨天的日期
yesterday=$(date -d "yesterday" +%Y-%m-%d)
# 新建日期文件夹
mkdir ${logs_path}/${yesterday}
# 如果存在 log，则移动当前 log 至备份目录
if [ -f ${current_logs_path}/access.log ]; then
mv ${current_logs_path}/access.log ${logs_path}/${yesterday}/access.log
fi
if [ -f ${current_logs_path}/error.log ]; then
mv ${current_logs_path}/error.log ${logs_path}/${yesterday}/error.log
fi
# 执行压缩
cd $logs_path
tar -zcvf ${yesterday}.tar.gz ${yesterday}
# 删除源文件夹
if [ -f ${logs_path}/${yesterday}.tar.gz ]; then
rm -rf ${logs_path}/${yesterday}
fi
# 向 Nginx 主进程发送 USR1 信号以打开新的 log 文件
nginx_pid=$(cat /usr/local/nginx/logs/nginx.pid)
kill -USR1 $nginx_pid

Cron job 自动执行脚本

Cron 是 Linux 中基于时间的任务管理工具，也就是定时任务。使用以下命令可新增/编辑 Cron job：

1

$ crontab -e

新增以下两个定时任务（需确保两个 Bash shell 文件具有..可执行..权限，若无权限可使用 chmod +x filename 命令添加）：

1
2
3
4


# 凌晨3点执行压缩 Java 应用 log 脚本
0 3 * * * /usr/local/bash-shell/java-log-compress.sh >/dev/null 2>&1
# 0点执行 Nginx log 切分、压缩
0 0 * * * /usr/local/bash-shell/nginx-log-compress.sh >/dev/null 2>&1

>/dev/null 2>&1 表示将 Cron job 错误级别的输出（2>）等同于（&）标准级别的输出（1），都丢到黑洞里（/dev/null），表示不记录输出，想要记录输出内容可设定为 >/var/log/cron.log 2>&1。

添加成功后查看已有的 Cron job：

1

$ crontab -l

References & Resources

《中台产品经理宝典》读书笔记

xuezenghui6@gmail.com (Zander Hsueh) — Sun, 07 Nov 2021 21:20:20 +0800

食之有味

P4. 产业基本发展规律：

所谓“三段式产业发展规律”，就是指：如果站在一定高度来看，对于包括互联网在内的任意一个产业，其产业周期都可以根据企业核心竞争力的中心而划分为技术时代、产品时代、市场时代 3 个发展阶段，并不断循环更替。

之前和领导聊天的时候也聊到过这里，范围缩小一点来说，一个互联网产品，最开始是由技术人员决定它的成长与高度甚至是成败与否，在产品投入市场后产品经理就是一个相当重要的角色了，他链接产品与用户，使得产品在用户体验、满意度等方面进一步提升发展，最终达到像今天我们使用的微信、抖音等成熟产品一样，由市场说了算，比拼企业的市场运作能力（反面教材快手），分别对应如上的三个发展阶段。

P35. 中台模式：

中台的核心本质就是向前台业务提供服务共享，目标是更好地支持前台业务方进行规模化创新或大规模试错，从而更好地响应市场需求。

中台模式是..业务层面..的「微服务架构」，而中台本身相当于 Spring Cloud 中的 Nacos 服务注册与发现的角色，用以调配对接各个业务模块之间或业务模块与不同终端之间的集成使用。支持大规模试错这一点与 MVP¹ 的概念也类似。

P58. 中台要把握的一个度：

怎么样真正让这个中台能够横向服务好每个业务，而不是变成一个障碍性的枢纽，这是最难的。

的确，类比一个轮子，封装地错综复杂不易用，就会变成一个障碍，然后被反复造，各行其道，那就失去了轮子的意义，失去了中台的意义。因此需要有一个能把握这个度的高业务眼界、高技术深度的人来引领把控方向，那个人在阿里可能是上面那段话的作者——张勇，在未来也未尝没有可能是你，是我。

P108. 商业模式画布：

假设我们要开发一款社交软件，首先我们要了解为哪类目标群体提供服务（用户细分），再确定他们的核心需求（价值主张），思考这款软件如何能被她们发现并使用（渠道通路），在用户开始使用软件后我们要怎么实现盈利（收入来源）以及与他们保持什么样的关系（用户关系），凭借什么特殊优势保证我们的这款软件的特殊性不会被竞争者超越（核心资源），为了达成这个目标我们需要采取什么活动（关键业务），最后能支持这个商业模式的合作方都有谁（重要合作），在整个计划开始前我们需要预估整个流程的综合成本会是多少和是否有盈利的可能性（成本结构）。

商业模式画布适用任何行业的任何企业，厘清企业中的这九个模块有助于针对性地从某个模块切入或扩大利润或降低成本来为企业优化创收达成商业目标。

余味回甘

一本全方位解读「中台」的好书，后半部分内容可作为中台系统建设的参考纲要。目前虽没有参与过中台的建设，但只从「解耦」这一个层面来讲，从开发的微服务架构中就已经窥到、意识到了其长远优势，常见的用户中心、鉴权中心，其实都算是中台的部分实现。再舍身处境地将自己当前遇到的一些其它业务难题带入到中台架构中，也的确会得到不少优化解。中台，难在实践，重在实践，建设成本不可谓不小。

最简可行性产品，见最簡可行產品。 ↩︎

《阿里云运维架构实践秘籍》读书笔记

xuezenghui6@gmail.com (Zander Hsueh) — Sat, 16 Oct 2021 22:43:40 +0800

食之有味

P73. CAP 定理：

CAP 定理（CAP theorem）指出，对于一个..分布式..系统来说，其不可能..同时满足..以下 3 点：

Consistency（一致性）：所有节点在同一时间具有相同的数据。
Availability（可用性）：保证每个请求不管成功或者失败都得到响应。
Partition tolerance（分区容错性）：系统中任意信息的丢失或失败不会影响系统的继续运作。

这里推荐阮一峰的《CAP 定理的含义》协助理解，各数据库模型的实现其实就是对 CAP 定理三个特性的不同取舍。

P79. SQL 语句优化：

80% 的数据库性能问题都出在 ..SQL语句..上。
80% 的 SQL 语句性能问题都是由..索引..引起的。

这让我又想起曾经遇到的业务问题，事出正是慢查询，而处理这个性能问题时也正是通过先优化 MongoDB 的查询语句——前置业务查询条件及分页查询条件，再优化数据库索引得以缓解。这属实是慢查询的最佳实践了🎉。

P192. 存储引擎与服务器配置：

由于 MongoDB 存储引擎基于内存映射，因此..高内存..的配置能有效提升 MongoDB 的性能。

P254. K8S 部署应用：

在使用容器编排技术时，为了让对应容器高可用，也为了让机器性能的利用率更高，因此容器会根据状态是否存活，以及机器性能使用高低的情况，在不同的节点之间调度漂移。加上本身 K8S 就会消耗机器性能，所以总体来说，K8S 不适合部署对性能配置依赖很高的应用。这就间接说明了为什么我们一般很少将数据库部署在应用中，而是把业务代码部署在容器中，因为这样可以实现快速部署。

P278. 云端 DevOps 最佳实践：

GitLab + Jenkins + K8S + 微服务是云端 DevOps 的最佳实践。

没错，正是我们当下在做的！

P333. 缓存五分钟法则：

即如果一条记录被频繁访问，就应该考虑放到缓存里。否则的话客户端就按需要直接去访问数据库，而这个临界点就是五分钟。

余味回甘

使用缓存牺牲了什么？

书中一直有一个说法：「缓存是一种典型的以牺牲数据时效性换取访问性能的技术」，我不太赞成这种说法。因为这样的表达是在说：使用缓存的缺点是没有或者减少了数据的时效性，我觉得这没有结合实际业务中使用缓存的前提——开发者肯定是在需要使用缓存的业务情景下才使用缓存的，也就是说我们为某个数据使用了缓存是..知其可用性..的，并没有牺牲什么实质性的时效性，这不算作是使用缓存的一种牺牲，缓存，就是临时存储在内存中的一组数据，该用时用，不该用时不用。

我的爷爷

xuezenghui6@gmail.com (Zander Hsueh) — Tue, 13 Jul 2021 21:43:00 +0800

近来因琐碎家事，思绪万千，难以入眠。也理所当然地忆起了一个带给我童年欢乐与依靠感，并足以影响我一生的人——我的爷爷，便想着写篇文字，一是在这繁乱嘈杂的世界中趁记忆还尚未消散将其持久化，以后看来，笑也好，苦也罢，总是值得。二是借现代互联网的特性，谨纪念一位几十年如一日无怨无悔奉献自我、影响他人的人民教师、至善之人，任何事物被历史淹没都是必然，但我也想让他能泛起些浪花。¹

我的爷爷生于 1936 年 9 月，普通的穷苦农民家庭，那时家里虽过得艰难，爷爷自幼却努力刻苦，识字读书，受了教育。19 岁还在上学的爷爷经人介绍与奶奶结婚，20 岁投身教育事业，在家乡的中学教授语文，后也带过班级当了很多年班主任。至 1998 年退休共执教四十余载，不说桃李满天下，但也倍有才人出。

工作所需他借此也算游过大江南北，登顶华山走过长空栈道，坐过渡轮去达杭州西湖，这些阅历在那个年代不可谓不丰富。爷爷是个极其顾家的读书人，文革期间，爷爷的转正受到了影响，每月 27 元工资拿了十数年，中间许多人因为工资难以糊口不做老师了，爷爷念叨着不做了不做了却一直坚持，只不过空闲时拼了命下田干活挣工分，得以养家。可有人看不下去了，咬定爷爷家是“富农”成分，为此爷爷只身一人前往北京上诉，才得以平反。我的记忆里，他还有着这几大爱好：

一、看书。常听奶奶念叨爷爷年轻时爱买书，可能因为勤俭持家的缘故，这个爱好在我的记忆里已经不太鲜明了，但从家里堆的几箱书也可以见得不假，有我小时候也翻过的《鲁迅全集》，有竖着排版的《聊斋志异》，有我小学作工具书用的《汉语言字典》（可惜这些书由于一些原因见不到了，一大憾事）。爱看书我是真的切有感受，老头子经常在院子里戴着自诩舒服的“石框眼镜”看得入迷呢，不管报纸书籍甚至领来的广告小刊。

二、写字。为什么爱写毛笔字这个问题我问过爷爷，得到的答案是——教书时在学校闲着没事干，但这没事干练出来的字可是被乡里乡亲大大认可了，无论红白喜事的礼单执事单，还是逢年过节的春联灵位，都得找薛老师提笔落墨。为了方便他还收集素材，把知道的见到的好联都抄记在小本子上用时查阅，不仅如此，还教了我祖宗灵位的书写格式，当时我记录在 QQ 空间，得以如此，这些年过年祭祀祖宗时家里和几个同乡邻居家都用上了。

我看得出来，爷爷是喜欢写字的，看鲁迅的他肯定知道文字是有力量的。想来也是，在邻居侵占门口公共道路用地私建“自家”院落时，爷爷也曾写下多封举报信诉其无法无德，想以文字散发力量，可惜彼时小县城的相关机构腐败无能，投诉无果，只靠公序良俗又怎么能限制得了这小乡村的流氓泼妇呢？最终只落下一句“人善被人欺”。

三、捡柴禾。这个爱好和职业无关，但深深刻在我的印象里。以前家里烧火做饭，免不了需要柴禾。爷爷是个闲不下的人，每逢下雨河里发水便去捞从山里冲下来的树枝木棍，到现在想来都尽是一副穿着背心挽着裤腿的形象，结果就是家里房檐下院落中总是整整齐齐堆着劈好的烧不完的柴禾。与此同时，因为总在冰冷的河水里待着，爷爷的腿被刺激得血管凸起落下毛病，尽管如此家人还是劝说不动，他把这当成了一个爱好、一种付出。

要说爷爷与我，那趣事可真的一堆呢。我是家中最小的孩子，从小受爷爷奶奶的宠爱也自然多些，很小的时候，爷爷家养了头大黄牛，犁地拉车的算是为这个家做过不少贡献，爷爷可是很爱护这头功臣的，青草面汤好生“伺候”，还经常拉出去溜溜。可架不住我非要骑上一骑这大黄牛啊，一番撒泼打滚后爷爷抱起我让我两腿一跨骑在那大黄牛上一顿“驾！”，那时一翁一童的放牛日子真是悠哉，走在山间路旁，听他给我讲为什么这个坡叫刺坡，为什么那个沟叫大烟囱沟。

龙口²的对岸是刘家，荒野山下只有一个小房子住着一个老头——刘家老汉，孤苦伶仃只有一条狼狗作伴，靠着门前的桃树、杏树、梅李换取生活所需。爷爷喜欢过去跟他闲谝，夏天还经常带我过去玩，抱着个大西瓜拿过去给刘家老汉，老汉门前没熟的梅李现在想想都酸！后来刘家老汉去世了，村民这才想起他家还有那么多果树，掠夺殆尽。

我小时候不懂事，在现在看来是个极其残忍之人，经常用各种道具残杀门口弱小的蚂蚁🐜，火烧水淹无所不用其极，爷爷看到了一定会制止我，脾气极好、一本端正地告诉我这样做不对，蚂蚁再小也是条命儿。也许是由于这样的敦敦教诲，也许是心智成熟了，后面的我看见蚂蚁飞虫都不忍踩踏，甚至还有些怯惧。

六年级我转学去了县里，周五总是爷爷骑着那辆听他说一次驼过几百斤粮食的二八自行车接我回家，他不紧不慢地蹬着自行车走在还未通车的高速路上，我坐在后座问着小脑袋里冒出的各种古怪问题。到了初中以后，每个月爷爷都用他攒来的工资（记得我很小的时候爷爷工资一个月才 30 元）和退休金拨给我们几个孩子生活费，不厌其烦地教导我们要好好学习，将来做一个对社会有用的人。

在我高中的时候，爷爷的身体就不好了，再到后面就病重卧床了，这段艰难的日子他只有半夜疼醒时才会对奶奶诉说自己的病痛，他人再问都是“不要紧”来搪塞。让我忘不掉的是每每我周末回家时，爷爷都拉着我的手说最放不下的就是我，盼我出息，毕业后有个好的安顿，与对象的事能有个定数。于我而言，这段时间也是最让我追悔的，一是陪伴爷爷的日子太少了，二是没带对象去看看他，让他安心。最让我痛惜的是 2016 丙申年的春节前夕，爷爷走的那天我正好不在，从此便深知珍惜眼前人，莫使人去空流泪。

他操劳一生，生前就安排好了自己后山的葬处，一些事更是在走后才知道，好衣服舍不得穿都压在箱底，给奶奶专门留了养老钱怕受委屈……虽然我是一个无神论者，但心里还是希望在那边的爷爷能多心疼心疼自己，也希望他能看到今天的笔者，得以欣慰，甚至骄傲。也许未来从我的整个人生历程来看，有爷爷的陪伴的日子并不很长，但我对爷爷的印象却远超父亲，无论是做人还是做事，都对我影响至深。

还有一部分原因是受温总理《我的母亲》一文影响，也想抒发一些情感。 ↩︎
家乡门前河流上游的一个大水潭名。 ↩︎

前端工程化之 npm 私服

xuezenghui6@gmail.com (Zander Hsueh) — Wed, 28 Apr 2021 16:30:30 +0800

工程化系列的上篇文章讲到了组件的发布及使用，这篇文章就来看看如何..高效..搭建..易用..的私有组件仓库。

组件有跨项目共用的需求，也就要考虑到组件代码的存储和传播了，排除了 Bit 后满足这两点的最适宜内部组件存储的介质就是 npm 私有仓库了，它具有以下几个特质：

安全性：只有内网可访问，避免代码泄露
复用性：与 npm 公共库一样便于下载传播
版本管理：统一管理组件库版本，语义化版本号

再综合考虑其它因素如搭建复杂度、框架量级、业务场景，我们选择了使用 Verdaccio 来搭建公共组件仓库。

Verdaccio 介绍

Verdaccio 是一个基于 Node.js 的轻量化私有 npm proxy registry，proxy registry 对应的便是 npm 官方的 public registry，具体概念见 registry | npm。简而言之，Verdaccio 的本质作用是管理发布上来的 npm 包，并且使之与官方包隔离，易用性主要体现在这些地方：

配置方式简单
权限控制清晰
开箱即用的 Web 界面

搭建组件仓库

安装 Verdaccio

私有的组件仓库要能被其他开发人员访问，就要放在服务器上了。确保服务器安装好 Node 环境后，全局安装 Verdaccio：

1

$ npm install -g verdaccio

安装好后终端输入 verdaccio 即可启动服务，由于 Verdaccio 是一个 Node 服务，会随着终端关闭终止服务，可使用 PM2 管理：

1
2
3
4


$ pm2 start verdaccio # 启动服务
$ pm2 list # 查看服务列表
$ pm2 log <id> # 查看日志
$ pm2 stop <id> # 关闭服务

成功启动服务后 log 中会显示四条主要信息：

1
2
3
4


warn --- config file - /root/.config/verdaccio/config.yaml # 配置文件位置
warn --- Plugin successfully loaded: verdaccio-htpasswd # 鉴权插件
warn --- Plugin successfully loaded: verdaccio-audit # 审核依赖插件
warn --- http address - http://localhost:4873/ - verdaccio/5.0.1 # 服务入口

此时浏览器访问服务器的 4873 端口（云服务器需确保在安全组开启该端口）可进入私有仓库的 Web 界面，当然了，目前还是比较简陋的。

配置 Verdaccio

Web 界面、插件、权限等配置都在启动时日志显示的配置文件中修改，编辑该文件为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


# /root/.config/verdaccio/config.yaml

# 数据的存储位置
storage: /root/.local/share/verdaccio/storage
# 插件目录位置
plugins: ./plugins

# web 界面配置
web:
 # 网页标题
 title: Verdaccio
 favicon: https://xuezenghui.com/favicon.ico
 # web 界面语言
 i18n:
 web: zh-CN

auth:
 htpasswd:
 # 存储用户认证信息的文件地址
 file: ./htpasswd
 # 最大用户数，设为-1表示不允许自行注册
 max_users: 100

# 私有仓库没有找到包时的查找路径
uplinks:
 npmjs:
 url: https://registry.npmjs.org/

packages:
 '**':
 access: $all
 publish: $authenticated
 proxy: npmjs

server:
 keepAliveTimeout: 60

middlewares:
 audit:
 enabled: true

logs:
 - { type: stdout, format: pretty, level: http }

初始化组件仓库

接下来需要将上次封装好的组件发布到配置好的私有 npm 仓库中，具体步骤：

1. 本地注册 Verdaccio 用户

本地注册用户需执行 $ npm adduser --registry <IP 地址:4873> 并按提示输入用户名、密码和邮箱，完成后可在 Web 界面进行登陆查看仓库内容，也才能在本地发布/使用私有的 npm 包。

但我们不能允许任何人都可以注册用户，所以通常需要设置配置文件中的 max_users 属性为 -1 禁止自行注册，需要注册时可使用官方工具 Htpasswd Generator 创建密钥信息，由管理员添加进htpasswd文件中，避免反复打开/关闭配置文件中的属性。

2. 项目文件及配置

先给公共组件项目创建软件包的代码仓库 lib 目录，创建 lib/components.js 文件来处理仓库中的 Vue 组件，文件内容与 src/utils/global.js ..基本..一致：

要注意的是lib目录里不能使用别名导入文件，比如表示 src 目录的 @，需替换成相对路径。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


import Vue from 'vue';
import upperFirst from 'lodash/upperFirst'
import camelCase from 'lodash/camelCase'
const requireComponent = require.context('../src/components', true, /\.vue$/);
requireComponent.keys().forEach(fileName => {
const componentConfig = requireComponent(fileName);
const componentName = upperFirst(camelCase(fileName.split('/').pop().replace(/\.\w+$/, '')));
Vue.component(`Z${componentName}`, componentConfig.default || componentConfig)
});

将 Vuetify 配置一并导出，确保仓库中的组件与组件仓库里穿着同样的「衣服👔」：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


import Vue from 'vue';
import Vuetify from 'vuetify/lib';
import '@mdi/font/css/materialdesignicons.css'
import '@/assets/sass/main.scss'
Vue.use(Vuetify);
const theme = {
primary: '#6DA4D8',
secondary: '#FDDB55',
error: '#EF3A61',
success: '#51AD5A',
info: '#6DA4D8'
};
export const options = {
theme: {
themes: {
dark: theme,
light: theme,
},
},
icons: {
iconfont: 'mdi'
}
}
export default new Vuetify(options);

创建包的入口文件 lib/main.js，引入样式和所有组件：

1
2


import '../src/assets/sass/main.scss';
import './components';

然后在package.json文件中设置好包名name、版本号version等描述信息，添加main指定包的入口文件，添加files指定库中包含的文件目录，并修改属性private为false保证包可被发布，这部分与 npm 发布包一致，参考 package.json | npm Docs。

1
2
3
4
5
6
7


+- "private": false,
++ "main": "lib/main.js",
++ "files": [
++ "lib",
++ "src/assets",
++ "src/components"
++ ]

3. 发布公共组件

指定 register 地址发布包到私有仓库：

1

$ npm publish --registry <IP 地址>

发布成功后会显示包的一些元数据：

访问 Web 界面可看到包的基本信息：

当然了，组件库应该设置一定的读写权限来控制包的使用和发布权限，Verdaccio 中包的使用权限逻辑默认是这样的：

如果你配置了账户，那么你就能登入 Web 界面查看库中软件包的详细信息，有了包名和 registry 地址，你就能安装使用了。也就是说，有无账户体现在对包的可见性。

权限在配置文件的packages下添加：

1
2
3
4
5
6


packages:
 'my-components':
 # 使用权限
 access: $authenticated
 # 发布权限
 publish: zander

权限设为 $all 表示任何人对这个包有相关权限，$authenticated表示只有经过验证的有权限，此处发布权限设为了固定的用户，在进行 publish 操作时 Verdaccio 会根据用户注册时自动生成的authToken（可通过$ npm config ls -l命令查看）进行鉴权。

使用公共组件

OK，至此，NPM 私服就已经搭建完成了，而后其它项目中便可以像使用普通 npm 包一样简单地使用企业内部公共组件了，先安装组件 npm 包：

1

$ npm install my-components --registry <IP 地址> -D

本案例中使用了 Vuetify 组件库，因此使用公共组件的项目中要正确显示组件样式需确保安装完整 Vuetify 的相关依赖，推荐使用 $ vue add vuetify。

最后，在 src/main.js 中引入组件：

1

import 'my-components';

Now, enjoy your components in the global Vue!

1

<z-btn large color="yellow">🎉🎉</z-btn>

结语

这篇文章拖了挺久的，学习和再总结的过程花费了不少时间，但工程化相关的探索似乎才刚刚开始，也如我所说，在项目迭代、人员变动等影响因素下去实际运用抽离的组件，推动团队的组件化进程才是步履维艰的。

组件管理也应有一个合理的流程，协调好 UI 设计者、组件开发者、测试者和使用者等参与人员的流程关系同样重要，我总结了一个组件定义的流程图，我们团队目前在遵循此流程：

另，本文涉及的代码位于我的 GitHub：

Xuezenghuigithub/my-storybook

夸克之细节设计

xuezenghui6@gmail.com (Zander Hsueh) — Mon, 01 Mar 2021 10:25:49 +0800

想众友已多闻 IOS 与 Android 皆有一极简好用之浏览器具，名曰 Quark —— 夸克。众所周知，于移动端而言，因原生应用之体验深度高、功能集中性强，浏览器多于搜查问题、访问站点等场景时，作工具之用。

既是工具，但求用其时..有惊人之效速，无广告之烦扰..，简约简洁，达意即可。也正因如此，夸克得以脱颖而出，广受好评。

且慢，本文并无强行安利之意，而是近日，缘追剧之因，余见其一细节之设计，深得吾意，遂尝分享。

是时，于网站内用夸克之内置视频播放器观剧，吾初右手持机，点击屏幕右侧，锁屏等按钮现于右侧，并无惊奇：

且当我换左手持之后，便只可触碰到屏幕左侧之区域，欲靠右侧来解锁屏幕相当不便，然当左手点击左侧屏幕时锁屏等按钮即现于左侧😺，妙哉妙哉：

此功能虽仅靠监听点击事件以判断区域即可实现，然于一普通用户而言，设计即是设计，与实现方式并无牵连，与华丽外表形意不大，且至少，于其它播放介质之上，皆不见如此为用户之考虑。

末，以乔布斯之言了结罢：

“The design is not just what it looks like and feels like. The design is how it works.”

前端工程化之组件化开发

xuezenghui6@gmail.com (Zander Hsueh) — Tue, 09 Feb 2021 11:31:30 +0800

时隔一年，Bit 情理之中地没有🔥起来。So, 我们团队经过对其它组件管理工具的 POC，同时把 Bit 做不到的事情作为重点来考量，确定了 Storybook + NPM 的技术方案来开发和管理前端共用组件，并且正巧撞上了 Storybook 6.0，组件的定义方式和组件文档的撰写方式都有很大程度的突破，更适合前端开发人员了¹，这点我是通过不同版本的使用切实体会到了👍。6.0 同时应广大使用者的吐槽重写了 Storybook 的官方文档，可在目前来看依然存在一些问题，比如没有中文版本、没有 Vue 的示例代码，着实让我们在实践的过程中费了不少功夫，但好在终九转功成，集成组件预览、动态更新、参数说明等功能的自动化前端共用组件平台成功搭建运转🎉。

组件化其实并不难，只需要考虑三个问题：

如何..定义..组件？
如何..展示..组件？
如何..共用..组件？

1难在如何根据业务维度抽离组件，同时也考验组件封装的能力，也就是代码的基本功了；2难在展示工具的选取和实际用法，很庆幸，这趟浑水我已经替看到这篇文章的你淌了😌，答案就是 Storybook；第3个问题先抛开技术难度，它更考量整个团队的协作度去实际运用抽离的组件，共同推进组件化进程，这无疑才是最难实现的，否则整个工程化又有什么意义呢？(自省)

初始化组件文档

组件文档的目的是展示共用的 UI 组件，将来需要部署至线上，因此它本质上就是一个站点，而 Storybook 就是生成这个站点工具，它能与项目的主程序隔离构建和运行。Storybook 做的其实很简单，它能给你的每一个组件添加一个..故事..，在这个故事里可任由你对组件点缀发挥，最后它将这一个个故事放在生成的站点上，就组成了《组件文档》。

创建项目，安装依赖

既然组件文档本质就是站点，那么按一个 Vue 项目来创建，再添加需要用到的依赖项：

1
2
3
4


$ vue create my-storybook
$ cd my-storybook
$ vue add vuetify
$ npx sb init # 安装Storybook

本文基于 Vuetify 2.4.0 进行组件抽离封装，其它 UI 组件库需自行验证与 Storybook 的结合方式。

成功后执行 $ npm run storybook 会启动 Storybook 并自动在浏览器打开网页，默认使用的是6006端口，不与 Vue 冲突，所以开发组件时可以使用 Vue 项目实时预览组件的改动，开发完成后再引入 Storybook。

目录及配置

Storybook 配置

.storybook 目录下存放 Storybook 的配置文件，修改主配置文件 main.js：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


/* 文件位置：.storybook/main.js */
const path = require('path');
module.exports = {
// 故事文件的放置目录
 stories: ['../src/stories/**/*.stories.js'],
// 要用到的插件
 addons: ['@storybook/addon-actions', '@storybook/addon-links'],
// Storybook的webpack配置
 webpackFinal: async(config, { configType }) => {
// 配置可在故事文件里使用别名
 config.resolve.alias['@'] = path.resolve(__dirname, '..', 'src');
// 配置解析 Sass
 config.module.rules.push({
test: /\.s(a|c)ss$/,
use: ['style-loader', 'css-loader', 'sass-loader'],
include: path.resolve(__dirname, '../'),
});
return config;
}
};

Vuetify 配置

主题色、辅色等 Vuetify 相关的配置在自动生成的 src/plugins/vuetify.js 文件中。这里建议直接引入 vuetify/lib，因为默认的 vuetify/lib/framework 内不包含样式部分，Vue 里是通过 vuetify-loader 编译的，而后面 Storybook 里没有 vuetify-loader，会导致样式失常，直接导入 vuetify/lib 一劳永逸😎。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/* 文件位置：src/plugins/vuetify.js */
import Vue from 'vue';
import Vuetify from 'vuetify/lib';
Vue.use(Vuetify);
const theme = {
primary: '#6DA4D8',
secondary: '#FDDB55',
error: '#EF3A61',
success: '#51AD5A',
info: '#6DA4D8'
};
export const options = {
theme: {
themes: {
dark: theme,
light: theme,
},
},
icons: {
iconfont: 'mdi'
}
}
export default new Vuetify(options);

装饰器

基于特定 UI 库的组件需要搭配装饰器 Decorators 来在 Storybook 中渲染，创建全局装饰器文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


/* 文件位置：.storybook/preview.js */
import Vue from 'vue';
import Vuetify from 'vuetify';
import { options } from '@/plugins/vuetify'
Vue.use(Vuetify)
export const parameters = {
// 自动为组件文档中的事件匹配参数
 actions: { argTypesRegex: "^on[A-Z].*" },
}
const vuetify = new Vuetify(options)
export const decorators = [
(story, context) => {
// 包装组件
 const wrapped = story(context)
// 返回 Vue 子类，表示每一个故事在Storybook里渲染出来都是一个完整的Vue实例
 return Vue.extend({
vuetify,
components: { wrapped },
template: `
 <v-app>
 <v-main>
 <wrapped />
 </v-main>
 </v-app>
 `
})
},
]

如果你在 Vuetify 的配置文件里非要引入 vuetify/lib/framework，那么需在这里另外引入样式文件 import 'vuetify/dist/vuetify.min.css';。

上面就是确保 Storybook 可正常渲染 Material Design 风格组件最基本的配置了，当前步骤的目录可参考：

.
├─ .storybook/
│ ├─ preview.js
│ └─ main.js
├─ doc/
├─ node_modules
├─ public/
├─ src/
│ ├─ assets/
│ ├─ components/
│ ├─ plugins/
│ │ └─ vuetify.js
│ ├─ stories/
│ ├─ App.vue
│ └─ main.js
└─ README.md

抽离封装组件

前端抽离划分组件的目的是降低页面的耦合度，解决页面内或页面间的代码复用性问题，但并不是说要划分得越细越好，无脑地抽离导致遍地皆组件没有什么意义，而是一定要从业务出发，考虑业务使用的场景和逻辑的合理性，不同公司、不同业务甚至不同项目之间组件的可代入性和可替换性都是无法确定的。所以这里只从技术角度出发，以按钮组件 Button 重点看看..封装..组件的部分。

设置全局组件

为了不用在抽离组件时频繁引入组件、注册组件来预览，先配置 src/componnets/ 目录下所有组件为全局组件：

安装 lodash：

1

$ npm install lodash

创建文件 src/utils/global.js：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


import Vue from 'vue';
import upperFirst from 'lodash/upperFirst';
import camelCase from 'lodash/camelCase';
// 引入目录下的全部组件
const requireComponent = require.context('@/components', true, /\.vue$/);
requireComponent.keys().forEach(fileName => {
// 获取组件配置
 const componentConfig = requireComponent(fileName);
// 处理获取组件名
 const componentName = upperFirst(camelCase(fileName.split('/').pop().replace(/\.\w+$/, '')));
// 全局注册组件
 Vue.component(`Z${componentName}`, componentConfig.default || componentConfig)
});

引入文件：

1
2
3


/* 文件位置：src/main.js */
++ import './utils/global.js';

这样处理后，在组件目录下编写的所有 Vue 组件在任意位置都可直接使用：

1
2
3
4
5


<template>
<div>
<z-button />
</div>
</template>

封装 Button 组件

..二次封装..要求一定要对原组件属性和方法的使用了如指掌，必要时也需要深入源码探究组件功能的实现方式。先从业务角度出发确定按钮的使用场景，随之也就基本确定了需要用到的属性和方法，如：

color：按钮颜色
width：宽度
disabled：禁用
icon：指定为图标按钮
...

所以，Component Z-Button v0.0.1：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


<template>
<v-btn
:color="color"
:width="width"
:color="color"
:width="width"
:x-small="xSmall"
:small="small"
:large="large"
:x-large="xLarge"
:icon="icon"
:disabled="disabled"
v-on="$listeners"
>
<slot></slot>
</v-btn>
</template>
<script>
export default {
name: "Button",
props: {
color: {
type: String,
default: 'primary'
},
width: [String, Number],
icon: Boolean,
disabled: Boolean,
small: Boolean,
xSmall: Boolean,
large: Boolean,
xLarge: Boolean
},
};
</script>

其中，v-on="$listeners" 直接监听组件的原生事件，比如点击事件直接在使用时绑定即可。<slot></slot> 插槽给组件提供了较高的可自定义程度。预览组件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


/* 文件位置：src/App.vue */
<template>
<v-app>
<v-main>
<z-btn color="info" width="100" @click="hello">
<v-icon>mdi-heart</v-icon>
</z-btn>
</v-main>
</v-app>
</template>
<script>
export default {
name: "App",
methods: {
hello(){
console.log('hello');
}
},
};
</script>

编写组件文档

抽离封装好组件后再转到 Storybook 的部分，开始之前先完善两件事：

1. 安装用于生成文档的插件

1

$ npm install --save-dev @storybook/addon-essentials

1
2
3
4
5
6


/* 文件位置：.storybook/main.js */
module.exports = {
...
addons: ['@storybook/addon-actions', '@storybook/addon-links', '@storybook/addon-essentials'],
}

是的，这是 Storybook 6.0 的第一个“哇塞”，它可以让你零配置即可体验..组件文档..的奇妙，包括自动生成的文档、参数控制、操作记录等。

2. 处理 icon

默认使用的 icon 是通过 public/index.html 引入的，所以 Storybook 内无法显示，需手动安装：

1

$ npm i @mdi/font

在 src/main.js 和 .storybook/preview.js 中分别引入：

1

++ import '@mdi/font/css/materialdesignicons.css';

然后为你的组件创建故事吧🤡：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65


/* 文件位置：src/stories/Button.stories.js */
// 导入事件处理
import { action } from '@storybook/addon-actions';
// 导入组件
import ZBtn from '@/components/Btn.vue';
export default {
title: 'Vuetify Components/Button',
component: ZBtn,
// 详细的参数文档
 argTypes: {
color: {
description: '组件颜色，默认为主题色',
table: {
defaultValue: { summary: 'primary' }
},
},
width: {
description: '组件宽度'
},
xSmall: {
name: 'x-small',
description: '小尺寸按钮'
}
}
};
// 定义组件模板
const Template = (args, { argTypes }) => ({
components: { ZBtn },
props: Object.keys(argTypes),
template: '<z-btn v-bind="$props" @click="clickBtn">按钮</z-btn>',
methods: { clickBtn: action('click')}
})
// 导出默认的组件
export const Default = Template.bind({});
// 添加不同风格的组件
export const SizeBtn = () => ({
components: { ZBtn },
template: `<v-row align="center">
 <v-col> <z-btn x-small @click="click">x-small</z-btn> </v-col>
 <v-col> <z-btn small>small</z-btn> </v-col>
 <v-col> <z-btn>default</z-btn> </v-col>
 <v-col> <z-btn large>large</z-btn> </v-col>
 <v-col> <z-btn x-large>x-large</z-btn> </v-col>
 <v-col> <z-btn disabled x-large>x-large</z-btn> </v-col>
 </v-row>`,
methods: { click: action('click')}
});
export const IconBtn = () => ({
components: { ZBtn },
template: `<v-row align="center">
 <v-col> <z-btn icon x-small><v-icon>mdi-plus</v-icon></z-btn> </v-col>
 <v-col> <z-btn icon small><v-icon>mdi-plus</v-icon></z-btn> </v-col>
 <v-col> <z-btn icon><v-icon>mdi-plus</v-icon></z-btn> </v-col>
 <v-col> <z-btn icon large> <v-icon>mdi-plus</v-icon> </z-btn> </v-col>
 <v-col> <z-btn icon x-large><v-icon>mdi-plus</v-icon></z-btn> </v-col>
 <v-col> <z-btn disabled icon x-large><v-icon>mdi-plus</v-icon></z-btn> </v-col>
 </v-row>`,
methods: { click: action('click')},
});

这时会发现用于预览组件的容器太高了，没有自适应组件的高度，原因是 .storybook/preview.js 文件中用于包裹组件的 <v-app></v-app> 有最低高度 100vh 的默认样式，修改之：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* 文件位置：src/assets/sass/main.js */
// 取消最低高度
.v-application--wrap {
min-height: 0;
}
// 取消按钮英文大写
.v-btn {
text-transform: none;
}

1
2
3


/* 文件位置：src/plugins/vuetify.js */
++ import '@/assets/sass/main.scss';

然后，输入 $ npm run storybook 启动 Storybook 欣赏你的组件故事吧🎉🎉：

结语

完成组件和故事的编写后可将 Storybook 构建成静态 Web 应用程序来发布，以供团队之间共享，还可以利用 GitLab CI/CD 为其设置自动构建及部署，总之，它能做的真的很多，网上也不乏很多优质的组件文档值得我们学习。

写到这里发现篇幅拉的有些大了，而创建 NPM 私有仓库、将组件发布为 Package 以及组件的使用要说的还不少😌……也罢，那就且听下回分解。本文案例放在了我的 GitHub 以供参考：

Xuezenghuigithub/my-storybook

References & Resources

Configuring Storybook 6 for Vue 2 + Vuetify 2.3 | Morgan Benton

"The 6.0 release retools Storybook for professional frontend developers." ——Storybook 6.0 ↩︎

前端工程化之 CI/CD

xuezenghui6@gmail.com (Zander Hsueh) — Tue, 17 Nov 2020 15:20:01 +0800

在项目开展的过程中，我经常做功能分支-测试分支-部署分支之间的代码合并工作，虽然说我们团队有着合理的 Git Flow、Commit 规范，但确保不了每个开发人员在每次提交的时候都严格遵守，且在分支复杂、提交时间节点不确定的情况下，合并分支时产生冲突、处理冲突似乎成了不可避免的事，从开发的整个生命周期来看对产出效率的影响是不小的。

「工程化」还要考量的一个角度便是..生产效率..，也就是「自动化」，任何重复次数多于两次的简单机械劳动都应该交给机器来完成，这也就是前端工程化中“自动化”的过程，当然，不止前端了，任何需要频繁交付应用的团队都希望有一个工具、一种方法能应对“集成地狱”和机械化的部署工作。

CI/CD 概要

CI

Continuous Integration，持续集成。集成这个动作指软件开发过程中合并代码的过程，而持续集成指的就是我们需要的自动化的过程——在开发人员提交新代码后，自动进行构建、测试并合并代码到代码仓库中。

CD

CD 有两种含义，Continuous Delivery 持续交付和 Continuous Deployment 持续部署。持续交付指在完成应用的测试、集成和构建后因为团队要求或业务要求，自动将应用部署到..准生产环境..，能部署到准生产环境也就意味着可以直接部署到正式的生产环境，所以，持续交付意味着任何的代码修改可以在任何想要部署的时候实施部署，表示一种能力。

而持续部署则是一种实践，一个最终动作，表示在通过前面的所有阶段后自动将改动投入生产环境。不同的团队对持续交付和持续部署有一定要求，比如我司要求在部署到生产环境前先部署到准生产环境进一步测试。

GitLab CI/CD 实践

CI/CD 是 GitLab 的内置工具，不需要第三方工具就可以拿来即用。GitLab CI/CD 会根据用户创建的特定 YAML 文件使用 GitLab Runner 自动执行脚本，文件中的脚本即是我们需要执行的操作，如添加依赖项、构建、单元测试等等。

配置 GitLab Runner

存放脚本的 YAML 文件是关键，但首先需要有执行脚本的工具 GitLab Runner，每个要实行 CI/CD 的项目都必须指定一个特定的 Runner，Runner 是一个使用 Go 语言编写的类似终端的工具，可以运行在 Linux、Docker、maocOS 等众多环境中，可以选择配置三种不同类型的 Runner：

Specific Runners：项目特定的 Runner，适用于需要执行部署作业等有特定要求的项目
Shared Runners：由 GitLab 管理员安装、注册的可用于所有项目的 Runner
Group Runners：同样由 GitLab 管理员来安装，不同的是可以给特定的 Group 设置特定的 Runner

因为需要进行持续部署，部署的目标服务器需要和 GitLab 中的代码仓库通信，符合“需要执行有特定要求的项目”，先来创建一个 Specific Runners。此处以部署 Vue 项目为例，在云服务器（Ubuntu 18.04.5）上要做..安装..和..注册..两个步骤，注册即将安装的 Runner 与 GitLab 绑定以使其可通过 API 通信：

1. 添加 GitLab 官方存储库

1

$ curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash

2. 安装 GitLab Runner

1

$ export GITLAB_RUNNER_DISABLE_SKEL=true; sudo -E apt-get install gitlab-runner

3. 获取 URL 和 token

进入要添加 CI/CD 的 GitLab 项目的 Setting ➡️ CI/CD 页面（前提是你要有该项目的 Maintainer 权限），展开 Runners 面板，在 Specific Runners 找到 GitLab URL 和 token。

3. 注册 Runner

在 Ubuntu 中运行 $ sudo gitlab-runner register，按照指令依次输入 GitLab URL、token、描述、标签、执行者（本例输入 shell）²。

注册完成后在 Runners 面板下即可看到绑定成功的 Specific Runner：

更换 Runner 后需执行 $ sudo gitlab-runner restart 重启以生效。

编写脚本文件

.gitlab-ci.yml 文件需要在项目根目录下手动创建，这个 YAML 文件中的配置叫做 GitLab CI/CD 的管道 Pipeline，每当代码库更新时，GitLab 都会先按照管道中的内容在 Runner 上执行相应的作业 Jobs。Jobs 是 .gitlab-ci.yml 文件中的最基本单元，用来定义执行一个操作的条件和位于 script 子句内的操作具体内容，如：

1
2
3
4
5
6
7
8


stage: # 显式声明各阶段，并指定执行顺序
 - job1
 - ...

job1: # 自定义的 Job 名
 stage: test # 当前 Job 的阶段
 script: # 由 Runner 执行的 Shell 脚本
 - echo "Hello, Zander!"

stage 可以决定各个 Jobs 的执行顺序——同一阶段的 Jobs 并行运行，不同阶段的 Jobs 依照书写顺序执行，如果前面的 Job 失败，则将提交标记为 failed 并且不执行后续的 Job.。不止 stage 和 script，一个 Job 内可用的参数见 Job keywords。

在项目根目录下新建（最好是在本地工作区创建而不是线上，因为本地提交更改 push 后会直接运行管道操作，方便查看效果）.gitlab-ci.yml 文件，编写脚本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


stages:
 - build
 - deploy

build_site:
 stage: build
 script:
 # 打印内容
 - echo "Start build"
 # 安装依赖
 - rm -fr ./node_modules && npm install --registry=https://registry.npm.taobao.org
 # 打包构建
 - npm run build
 - echo "Build done"
 only:
 - master # 只在 master 分支代码发生变化时才执行该 Job
 tags:
 - test # 指定 Runner 的 tag（注册 Runner 时指定的）
 artifacts:
 - expire_in: 1 week
 - paths:
 - dist/

deploy_site:
 stage: deploy
 script:
 - echo "Start deploy"
 # 将构建好后的 dist 目录拷贝到 NGINX 的挂载目录上
 - rm -rf /var/www/cicd-test
 - cp -r ./dist /var/www/cicd-test
 only:
 - master
 dependencies:
 - build_site # 接收 build_site 传递的产物
 tags:
 - test

按思路，build 阶段应执行打包产生一个 dist 目录，再在接下来的 deploy 阶段挂载到 NGINX 的目录上就完成了项目部署，但管道的设定是每个 Job 启动时都会同步仓库中的 .gitignore 文件并自动删除其中声明的文件——dist 目录在 deploy 阶段开始的时候就没了。

所以脚本文件中需要使用到另一个参数 artifacts，我将它译为“产物”，表示在当前 Job 执行成功/失败后可以将指定的文件或目录保存到 GitLab，这样就可以在下面的 Jobs 中使用了，上面还指定了产物的过期时间。dependencies 用于在当前的 Job 中接收前面的产物，默认前面的所有 Jobs 里的产物都会往后传递，设为空数组则不接收任何产物。

push 之前还需要设定一下 /var/www 目录的权限，该目录默认属于 root 用户，而 Runner 运行时的用户是 gitlab-runner，权限交接：

1

$ chown -hR gitlab-runner:gitlab-runner /var/www/

推送更改后，在项目的 CI/CD 面板中可查看管道和 Jobs 的详细情况：

点击单独的 Job 也可查看详细的执行情况，UI 上的操作就不多介绍了，当管道内所有的阶段都执行完毕后，Vue 项目即部署成功：

还有一点值得一提，我在将新的 dist 目录拷贝到 NGINX 挂载目录时先是用的 cp 命令结合 -fr 参数，表示复制并..覆盖..原有的目录。出现的问题是每次管道运行完成后都不能及时地更新应用的内容，后查询得知是由 cp 命令的底层原理导致的，简单来说就是 cp -fr 并不能保证安全地替换原有文件，遂使用了 rm + cp 命令，一切正常🎉。

References & Resources

图源 https://www.mindtheproduct.com/what-the-hell-are-ci-cd-and-devops-a-cheatsheet-for-the-rest-of-us/ ↩︎
执行者可以决定 Runner 执行器可以进行的操作，详见 Executors。 ↩︎

前端工程化之定制 Vue CLI

xuezenghui6@gmail.com (Zander Hsueh) — Tue, 22 Sep 2020 15:12:22 +0800

前言

想来也算来有一段时间没有更博了，总是在有一些想法的时候被各种乱七八糟的事情打乱，具体说来话长了，不如这样总结吧——..职能有变..， ..有好有坏..。虽然能用来自我支配的时间变少了，但也不算毫无收获，列出几条最近做的还算系统性的工作：

编写产出团队开发协作规范
关于 UI 零件化的思考及简报分享
抽离封装前端共用组件，发布至 Storybook
定制适用于团队的 Vue CLI

之所以说这几件事比较系统化是因为我统一把它们归在了前端工程化这一类别中，目的都是“统一开发模式，简化开发过程”。当然，工程化这一议程和工作并不是一蹴而就的，工程化过程中产出成果是一回事，推广整个团队遵循各 Guidelines 又是另外一回事了。索性过程中是有一些比较有意义的成果可以拿出来记录分享的，比如本文要详述的如何定制适用于自己/团队的 Vue CLI。

Vue CLI 一定都不陌生了，Vue 官方提供的脚手架工具，是一套包含集成、构建、插件配置、图形化等功能的完整工具集。官方脚手架的目的是更轻量更简单，追求使用的..广度..，也就是要适用更多的开发者，当面临下面问题时就稍显无力，需要开发者做更多的工作，甚至是反复的更多工作：

团队对项目目录结构有严格的规范要求
定制化要求比较高，如需要使用特定的 UI 框架及工具类库
项目配置文件较多，如 ESLint 配置项、Apollo 配置项等
项目内包含预定义的共用组件
懒……

定制 Vue CLI

定制化的 Vue CLI 是基于 Vue CLI 的，所以开展之前应确保本地安装了 Vue CLI 并可以使用 $ vue create <porect_name> 命令成功创建项目。实现的原理是 Vue CLI preset，即在创建新项目时使用预定义的配置和要用到的插件，而这些预定义的内容支持放在 Git 上（包括 GitHub、GitLab 等），使用远程仓库中的 Preset 创建 Vue 项目时需要加入特殊的选项：

1
2
3
4
5


# GitHub
$ vue create --preset <username>/<repo> <vue_project_name>
# GitLab 私有服务器
$ vue create --preset gitlab:<my-gitlab-server.com>:<group>/<project_name> --clone <vue_project_name>

初始化 Preset 目录结构

以 GitLab 为例，创建一个新的 Project 后 clone 到本地，第一步需要初始化项目的目录结构，一般 Preset 由以下四个部分组成，当然加上 README 更好了：

.
├─ template/
│ └─ ...
├─ generator.js
├─ preset.json
├─ prompts.js
└─ README.md

开发的时候需要频繁地执行创建项目的命令来测试改动，使用 Git 仓库无疑太麻烦了，Vue CLI 也支持根据本地的文件来创建项目：
1
$ vue create --preset ./<my_preset> <project_name>

添加预定义文件

preset.json 是使用 $ vue create 命令时自动生成的预定义选项的 JSON 文件，MacOS 中位于 ~/.vuerc。文件里定义的内容在命令行中不进行交互提示，比如执行 $ rm ~/.vuerc 删除该文件后执行 $ vue create hello 会提示是否使用淘宝的 NPM 镜像提升下载速度及使用 Yarn or NPM 作为包管理工具，创建完项目后查看 .vuerc 文件的内容会显示选择的内容：

1
2
3
4


{
"useTaobaoRegistry": true,
"packageManager": "yarn"
}

之后创建项目时就会采用该预定义项，不再进行提示。所以可根据需求来在 preset.json 中定义需要添加哪些插件，以及一些简单的配置项：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
"useConfigFiles": true,
"cssPreprocessor": "sass",
"plugins": {
"@vue/cli-plugin-babel": {},
"@vue/cli-plugin-router": {
"historyMode": true
},
"@vue/cli-plugin-vuex": {},
"@vue/cli-plugin-eslint": {
"config": "prettier",
"lintOn": [ "save", "commit" ]
}
}
}

定义模板文件

template/ 目录用来定义使用脚手架创建 Vue 项目后生成的目录结构，即模板，比如我们团队 Guideline 要求的目录是这样的：

.
├── build/ # 生成压缩包
├── public/ # 静态资源，不需要 webpack 处理
│ ├── favicon.ico
│ └── index.html
└── src/
│ ├── assets/
│ │ ├── fonts/ # 字体文件
│ │ ├── images/ # 图片文件
│ │ └── styles/ # reset 样式及定义的常量文件
│ ├── components/ # 共用组件
│ │ └── base/ # 全局注册组件
│ ├── layout/ # 整体布局组件
│ ├── plugins/ # 插件文件
│ ├── filters/ # 全局过滤器
│ ├── router/ # 路由及拦截器
│ ├── store/ # 管理 vuex 全局状态
│ ├── utils/ # 工具类函数
│ ├── views/ # Vue 页面
│ │ └── Home.vue
│ ├── App.vue
│ └── main.js
├── .eslintrc.js # ESLint 配置
├── .gitignore # Git 忽略文件配置
├── .prettierrc.js # Prettier 代码风格配置
├── babel.config.js # Babel 配置
├── vue.config.js # Webpack 配置
└── README.md

可以先简单地将 template 下定义的目录和需要的目录保持一致，但有几点需要注意：

如果模板中没有定义 Vue CLI 本身就会生成的文件，则默认采用原来的，如 view/ 目录下的 Home.vue 和 About.vue 等
以 . 开头的模板文件需要将 . 改为 _，以 _ 开头的模板文件要定义成 __，否则无法正确渲染¹
空文件夹不会被正确渲染

还有一处踩的坑耗费了不少时间，因为我们项目中添加并配置了 Vuetify，需要在 main.js 中引入并注册到 Vue 实例中，但如果将整个文件替换为新的内容，会报错 router、store 等..重复定义..。经验证发现在 preset.json 中预定义的插件，不需要在模板下的 main.js 中自行导入和注册，只需要添加需要的内容即可，如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 路径：template/src/main.js

import Vue from 'vue';
import App from './App.vue';
Vue.config.productionTip = false;
import vuetify from './plugins/vuetify';
new Vue({
vuetify,
render: (h) => h(App),
}).$mount('#app');

因为 preset.json 中预定义了 vue-router 和 vuex，最终生成的 main.js 是完整的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


import Vue from 'vue';
import App from './App.vue';
import store from './store';
Vue.config.productionTip = false;
import vuetify from './plugins/vuetify';
import router from './router';
new Vue({
store,
vuetify,
router,
render: h => h(App)
}).$mount('#app');

扩展依赖包

genarator.js 文件用来为项目添加其它依赖，比如 UI 框架、工具类库等等，渲染 template 模板的操作也需要在该文件内完成。该文件需要导出一个函数，包含三个参数：

api：generator 实例，函数中可以操作该实例，比如扩展依赖、检查插件、查看版本等
options：定制 Vue CLI 时与交互式命令行结合使用，用来接收答案参数

rootOptions：预定义的所有内容，也就是 preset.json 中的所有内容，并且包含项目名称、src/main.js 中配置的说明等：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{
projectName: 'my-vue',
useConfigFiles: true,
cssPreprocessor: 'sass',
plugins: {
'@vue/cli-plugin-babel': {},
'@vue/cli-plugin-router': { historyMode: true },
'@vue/cli-plugin-vuex': {},
'@vue/cli-plugin-eslint': { config: 'prettier', lintOn: [Array] },
'/Users/zander/Desktop/zander-vue-cli': { _isPreset: true, prompts: true }
},
'src/main.js': Set(2) { 'router', 'store' }
}

1. 添加依赖项

为项目添加脚本和依赖项需要使用 generator 实例的 extendPackage() 方法，内容和 package.json 无异，根据依赖的类型声明 NPM 包名和版本即可，创建项目时会自行安装声明的依赖项：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


module.exports = (api, options, rootOptions) => {
api.extendPackage({
scripts: {
"serve": "vue-cli-service serve",
"build": "vue-cli-service build",
"lint": "vue-cli-service lint"
},
dependencies: {
"vue": "^2.6.11",
"vuetify": "^2.3.2",
"@mdi/font": "^5.5.55"
},
devDependencies: {
"@babel/core": "^7.11.4",
"@babel/preset-env": "^7.11.0",
"@vue/cli-service": "~4.5.0",
"vue-cli-plugin-vuetify": "^2.0.5",
"vuetify-loader": "^1.3.0",
"sass": "^1.26.10",
"sass-loader": "^8.0.2"
}
});
};

2. 渲染模板

使用 render() 方法来渲染 template 中定义的模板，该方法实际使用 EJS 进行渲染，可以传入一个相对路径的字符串，会将原本的目录直接替换。也可以传入 Hash 对象，文件对应文件来渲染（不能是文件夹），写多个 rander() 的话会依次执行：

1
2
3
4
5
6


 api.render('./template');
api.render({
'./.eslintrc.js': './template/_eslintrc.js',
'./.gitignore': './template/_gitignore'
})

3. 修改主文件

使用 API 同样可以实现对主文件 main.js 内容的修改，但……实在是有些复杂呢🤪，感兴趣的可参考官方文档，个人更推荐按上面的方式在模板里更改或继续往下看使用 EJS 的语法更改🎉。

交互式命令行

很多命令行操作都涉及对话的情境，比如 Git 操作、各种 CLI 操作，看起来比较 Geek，实现原理是 Node.js 的交互式命令行 Inquirer.js。要想自定义 Vue CLI 的对话内容需要用到 prompts.js 文件，该文件内应导出一个与 inquirer.prompt() 参数相同数据结构的..数组..，数组内每一个对象都作为一个命令行中的问题[^3]：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


module.exports = [
{
type: "confirm", // 问题类型
 name: "vuex", // 存储答案的 key
 message: "是否使用 vuex 进行全局状态管理?", // 问题的内容
 default: false, // 未选择时的默认值
 choices: [ // 可选项
 {
name: '是', // 选项
 value: true // 选项对应的值
 },
{
name: '否', // 选项
 value: false // 选项对应的值
 }
]
}
]

在命令行创建项目时 Invoking 阶段会进行交互式的对话：

当然，完成对话后应该按照不同的答案执行不同的操作，上面 genarator.js 文件中的函数的 options 参数就起到作用了，可以在函数中打印 options，答案以 Key-value 的形式保存在一个对象内：

1

{ vuex: true }

那么就可以根据该对象结合 generator 实例的各方法来操作了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


if (options.vuex) {
api.extendPackage({ // 添加依赖
 dependencies: {
"vuex": "^3.4.0"
}
})
api.render({'./src/store/index.js': './template/store/index.js'}); // 渲染 store 文件

api.injectImports(api.entryFile, `import store from './store'`); // main.js 中导入
}
api.render('./template/default'); // 默认渲染的内容

此时虽然使用 injectImports() 方法导入了 store 到 main.js，但还没有注册到 Vue 实例中。因为 render() 的实质是通过 EJS 来渲染，所以可以在文件中使用 EJS 的语法实现更细粒度的控制：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// 路径：template/default/src/main.js

import Vue from 'vue';
import App from './App.vue';
Vue.config.productionTip = false;
import vuetify from './plugins/vuetify';
new Vue({
vuetify,
<%_ if (options.vuex) { _%>
store,
<%_ } _%>
render: (h) => h(App),
}).$mount('#app');

当然，能自定义的内容还有很多，比如二次封装 Axios、~~添加 NPM 私服的依赖~~、自定义默认的布局等等，结合以上步骤依据具体情境添加即可。

References & Resources

见 Vue CLI | 文件名的边界情况说明。 ↩︎

说 Markdown

xuezenghui6@gmail.com (Zander Hsueh) — Sun, 19 Jul 2020 16:19:39 +0800

自大学接触前端开始也就慢慢接触了 Markdown，最开始在 CSDN 上用着默认的富文本编辑器，当时对富文本是没有什么优劣认知的，毕竟不是文本编辑器的深度使用者，转战 Markdown 是因为彼时网课老师的普及和多见的 GitHub 项目 README.md 文件。

现在，日复一日阅读和使用 Markdown 已一载有余，就来谈谈对 Markdown 的些许看法和使用建议。

Markdown 语言在2004年由约翰·格鲁伯(John Gruber)创建，初衷是希望「使用易于阅读、易于撰写的纯本文格式进行编写，然后可以转换为结构上有效的 XHTML（或 HTML）」。

Markdown 没有 RTF 格式¹复杂的语法，也没有 HTML 繁琐的 <> 结构（作为一名前端开发人员，真的厌恶这个符号），不使用任何编译器或编辑器也能很容易地识别要表达的内容。甚至使用过程中会让人感受不到这是一门..语言..、一个..规范..，它的确做到了简洁地让人只专注于创作，仅仅使用键盘多敲几个符号就解决了基本的排版问题。解决了基本的排版问题，但还有些问题是让人不能不提的：

1. 图片无法指定大小

众所周知，在 Markdown 中使用 ![alt](url) 语法可以插入图片，但对图片的大小控制完全无力，很多时候都会因为图片问题严重影响文档的美观程度。而要想自行控制图片大小，只能又在 Markdown 文件中使用 HTML 语法—— <image src="" width="">，这不就又偏离初衷迷失本意了吗？

2. 过渡依赖空格、缩进和空行进行排版

虽然每次编写时也都不会忘记在 Markdown 符号后追加空格，但缩进和空行可就说不准了。在程序员编写 md 时会经常在列表下编辑代码段，就像这样：

代码示例：
1

console.log('Hello World')

书写这样的格式要求代码段必须与上面的列表采用空行间隔 + 缩进，缩进的多少对排版格式也有着莫大的影响（上面为缩进四个空格的结果），规范的不明确让人又回头思索起了如何排版的问题🤯。

其次，对空行的要求很高，少敲一个回车会导致排版混乱，多敲一个又会导致空行极多，往往一篇文章的空行数量有近..三分之一..，而这又是不可避免的……

还有一个不是 Markdown 的锅但同样让人头大的问题，书写中文文章时需要频繁地中英文切换，全角半角符号经常性切换不及，写错了还不易发现。

说实话不太理解和认同 Gruber 拒绝标准化的想法和做法。

接下来推荐两个笔者常用的 Markdown 编辑器吧：

1. Macdown

一款 MacOS 上开源的 Markdown 编辑器，优点是界面简洁，..所见即所得..的编写模式，支持 LaTeX 公式、Mermaid，也支持图片以 Base64 拖入并显示于文档（奉劝不要尝试这种粗鲁的做法哈哈哈哈）。缺点是文档内容多了时上下滚屏会卡顿，还有如上图所示，对空行的要求较严格。

2. Typora

开源，支持 MacOS、Windows 和 Linux 三端，..实时预览..模式，同样支持 LaTeX 公式、Mermaid，还有文件目录、文档目录等功能，但这都不是最重要的，它内置的一款主题 Newsprint 实在是深得我意，与本博客的主题不谋而合，让人能极其舒适地码字：

Typora 还有效避免了缺少空行导致的排版问题，它会在隔离的 Markdown 符号上下都自动加入空行，但这种处理方式又导致要实现上面的「列表下编辑代码段」会特麻烦……总之还是上面总结的几点 Markdown 语言的问题导致的。

Rich Text Format，富文本格式。 ↩︎

不会吧？不会吧？不会有人还搞不懂 Vue 双向数据绑定原理吧？

xuezenghui6@gmail.com (Zander Hsueh) — Tue, 14 Jul 2020 09:04:24 +0800

我猜测这篇文章的访问量在博客 Analytics 的页面访问量榜单里应该是列位不低的，因为——我标题党了😳。

双向数据绑定一直被认为是各 MVVM 框架的核心特性，在开发中也是无时不刻都在使用。而我一直是作为一个看客去了解别人博文中的 Vue 双向数据绑定，没有自己去深究并手动实现过（反省）。这篇文章，我将从..设计模式..、 ..技术原理..、 ..原生实现..等多个方面去解析 Vue 中的双向数据绑定，当然了，在 Vue3 发布之际，也应了解下 Vue3 下的双向数据绑定。

概述

在 MVVM 架构下，数据层 Model 和视图层 View 通过 View Model 层进行连接和交互，这个 ViewModel 即为连接视图和数据的桥梁，作数据和逻辑处理工作，指的正是双向数据绑定。

双向数据绑定实现的效果就是在更新 JavaScript 中的数据（定义的变量）时同步修改视图（DOM 节点），修改视图时也同步回数据层：

以一个开发者的角度应该不难想到，视图到数据方向的改动需要监听 DOM 的变化再同步赋值给 JavaScript 的变量，比如给 <input> 添加 change 或 input 监听事件并在事件处理函数中给变量赋值，实际这也正是 v-model 指令做的很重要的一件事。

另一个方向，关键词还是「监听」——监听 JavaScript 数据的变化，再去相应更新 DOM，此处的监听及处理就是 Vue 的双向数据绑定实现方式——发布订阅模式 + 数据劫持。

设计模式

发布订阅模式也称为观察者模式，是一种行为设计模式，设计意图也很明显了，允许定义一种..订阅..的机制，在对象发生一定的事件时通知观察着这个对象的其它对象。所以发布订阅模式一定存在以下三个模型对象：

目标对象：被观察的对象。
发布者：当目标对象发生变化时，向其他对象发出通知。
订阅者：可以执行一些操作来反应发布者的通知。

真实世界中的发布订阅模式例子非常之多，比如你（订阅者）订阅了我的博客（目标对象），就毋需每次打开我的博客站点来查看是否更新了新博文，而我（发布者）会在每次发布新文章时都通过 RSS 在 RSS Feed Reader 等订阅工具上通知你。

换置到双向数据绑定中，订阅者就是一个用来操作各 DOM 节点的公共方法，需要观察数据的改动来改动自己（作出反应），数据就是被观察的目标对象，那发布者是谁呢？~~是尤大啊~~哈哈哈，其实是实现数据劫持的 Object.defineProperty() 方法。

技术原理

Object.defineProperty()

实现数据劫持的核心方法就是 Object.defineProperty() 了，它是 ES5 加入的标准对象方法，作用是给一个对象添加或修改属性。我们平时添加/修改对象属性更多使用的是点语法：

1
2
3
4


const obj = { name: 'Zander' };
obj.age = '18'; // 添加属性
obj.name = 'Bob'; // 修改属性

Object.defineProperty() 方法能让我们更细粒度地控制对象的属性，其可传入三个参数：

obj：要操作的对象，Object 类型
prop：要添加或修改的属性名，String 类型
descriptor：属性描述符对象，Object 类型

descriptor 被称为属性描述符，个人觉得官方文档描述的有些难以理解，其实它就是对象属性的一个标签、一个定义，总共有两种标签类型：数据描述符和存取描述符，规定一个属性只能有一个标签，并且：

如果这个属性是数据描述符类型，那么它的 descriptor 对象不能设置 get 和 set 属性
如果这个属性是存取描述符类型，那么它的 descriptor 对象不能设置 value 和 writable 属性

descriptor 对象总共有这些属性：

configurable：属性是否可被删除，默认为 false
enumerable：属性是否可枚举，默认为 false
value：属性对应的值
writable：属性是否可重写，默认为 false
get：属性的 getter 函数，用于读取属性的值
set：属性的 setter 函数，用于设置属性的值

看实例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


const obj = { name: 'Zander' };
// 添加具有数据描述符的属性，相当于 obj.age = 18
Object.defineProperty(obj, 'age', {
configurable: true, // 可删除
 enumerable: true, // 可枚举
 value: 18,
writable: true // 可重写
})
// 添加具有存取描述符的属性
let age = 18;
Object.defineProperty(obj, 'age', {
configurable: true,
enumerable: true,
get(){ return age },
set(newVal){ age = newVal }
})

要着重看的是后者，具有存取描述符的属性的同样可以通过点语法来访问和重写属性的值，但是，是通过设置的 get 和 set 方法来实现的，这一点打印一下 obj 就可以验证：

也就是说，无论是读取还是改动属性的值都会执行定义的方法，那……岂不是可以为所欲为了？比如在改动数据时作为发布者角色将改动通知给订阅者，数据劫持搞定？

DocumentFragment

频繁地操作 DOM 节点会引起页面的重排及重绘，这会极大地影响页面性能，Vue 中进行模板的解析¹就需要操作 DOM，使用到了 DocumentFragment 文档片段接口，它相当于一个 HTML 节点的..容器..，让我们可以在处理完子节点后都先存入该容器中，最后一次性将容器内所有的子节点都添加或插入到真实的 DOM 中，从而将操作 DOM 的次数减少为只有一次，很大地提升了页面性能。

比如要给一个 ul 标签添加 10 个 li，你可能会这样做：

1

<ul id="list"></ul>

1
2
3
4
5
6
7
8


const names = ['Zander', 'Bob', 'Tom', 'Simon', 'Paul', 'Mary', 'Lisa', 'Ruth', 'Susan', 'Linda'];
const ul = document.getElementById('list');
names.forEach(name => {
const li = document.createElement('li');
li.innerHTML = name;
ul.appendChild(li);
})

这就需要操作 DOM 多达 10 次，而使用 DocumentFragment 只需要操作一次 DOM：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


const names = ['Zander', 'Bob', 'Tom', 'Simon', 'Paul', 'Mary', 'Lisa', 'Ruth', 'Susan', 'Linda'];
const ul = document.getElementById('list');
const fragment = document.createDocumentFragment();
names.forEach(name => {
const li = document.createElement('li');
li.innerHTML = name;
fragment.appendChild(li);
});
list.appendChild(fragment);

原生实现

极简实现

先不考虑设计模式种种，单单使用表单监听 + 数据劫持来实现极简的双向数据绑定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>Zander</title>
</head>
<body>
<input type="text" id="input" />
<p id="data"></p>
</body>
<script>
const obj = {};
const input = document.getElementById('input');
// 数据劫持，实现数据->视图的绑定
 Object.defineProperty(obj, 'name', {
configurable: true,
enumerable: true,
get() {
return input.value;
},
set(newVal) {
input.value = newVal;
document.getElementById('data').innerHTML = newVal;
}
});
// 监听输入框，实现视图->数据的绑定
 input.addEventListener('keyup', () => {
obj.name = input.value;
})
</script>
</html>

较完整实现

从上面的极简实现可以总结一下实现双向数据绑定要注意的点：

整个数据层应该是 Object 类型，才能对每个数据进行数据劫持（所以 Vue 组件中的 data 必须是个对象或函数）
使用同一个数据的 DOM 节点可能是多个，也就是说目标对象和订阅者对象是一对多的关系

较完整的实现目标是这样的：

1
2
3
4


<div id="app">
<input type="text" v-model="name" />
{{ name }}
</div>

1
2
3
4
5
6


const vm = new ZVue({
el: '#app', // 实例的挂载元素
 data: { // 数据
 name: 'Zander'
}
});

综合以上，要实现双向数据绑定在编码层面我们需要：

Observer 观察者函数：监听所有数据的变化，当数据变动时获取最新的值并通知给订阅者（数据劫持）
Watcher 订阅者函数：当接受到观察者的通知和提供的数据后同步更新视图
Compile 解析器函数：解析 DOM 元素上的 v-model 指令和 {{}} 语法

具体实现步骤：

1. 维护一个订阅者..们..数组

因为使用同一个数据的 DOM 节点可能是多个，所以需要维护一个订阅者..们..数组，update() 是订阅者的原型方法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


class Dep {
constructor(){
this.subs = []; // 订阅者数组
 }
/* 添加订阅者 */
addSub(watcher){
this.subs.push(watcher);
}
/* 通知订阅者 */
notify(){
this.subs.forEach(watcher => {
watcher.update(); // 更新视图
 })
}
}

2. 实现 Observer 观察者函数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


class Observer {
constructor(data){
this.observer(data);
}
/* data 处理 */
observer(data){
if (!data || typeof data !== 'object') return; // data 必须为 Object 类型
 for (const key in data) {
this.defineReactive(data, key, data[key]);
this.observer(data[key]); // 递归处理 data 中的 Object 类型
 }
}
/* 数据劫持 */
defineReactive(obj, key, value){
const that = this;
const dep = new Dep(); // 每一个数据都对应一个订阅者们数组

Object.defineProperty(obj, key, {
configurable: true, // 可删除
 enumerable: true, // 可枚举
 get(){
Dep.target && dep.addSub(Dep.target); // 每当 DOM 中使用该值时，添加一个订阅者
 return value;
},
set(newVal){
if(newVal === value) return;
that.observer(newVal); // 如果修改的新值是 Object 类型，递归进行数据劫持
 value = newVal;
dep.notify(); // 通知所有订阅者数据更新了
 }
})
}
}

注意 data 必须是对象才能进行数据劫持，递归处理保证所有数据均被管理。

3. 实现 Watcher 订阅者函数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


class Watcher {
constructor(vm, value, callback) {
this.vm = vm; // 实例
 this.value = value; // 数据当前值
 this.callback = callback; // 调用的更新视图的方法
 this.oldValue = this.get(); // 数据的旧值
 }
/* 获取数据旧值 */
get() {
Dep.target = this; // 将订阅者实例赋值给 target
 const value = compileUtils.getValue(this.vm, this.value);
Dep.target = null;
return value;
/* 更新视图 */
update() {
const newVal = compileUtils.getValue(this.vm, this.value);
const oldVal = this.oldValue;
this.callback(newVal);
}
}

4. 实现 Compile 解析器函数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


class Compile {
constructor(el, vm) {
this.el = this.isElementNode(el) ? el : document.querySelector(el);
this.vm = vm;
// 进行编译
 if (this.el) {
// 使用文档片段存储节点
 let fragment = this.node2fragment(this.el);
// 执行解析器函数，识别 v-model 和 {{}} 语法
 this.compile(fragment);
// 将编译完成的节点插入到 DOM 中
 this.el.appendChild(fragment);
}
/* 判断传入的挂载元素是否是 HTML 元素 */
isElementNode(node) {
return node.nodeType === 1;
/* 将 el 中的节点放入文档片段中 */
node2fragment(el) {
const fragment = document.createDocumentFragment()
while (el.firstChild) {
// 是子节点才插入
 fragment.appendChild(el.firstChild);
}
return fragment;
/* 编译节点 */
compile(fragment) {
let childNodes = Array.from(fragment.childNodes)
childNodes.forEach((node) => {
if (node.nodeType === 1) {
// 元素节点
 this.compileElement(node);
} else if (node.nodeType === 3) {
// 文本节点
 this.compileText(node);
} else {
return;
}
});
/* 编译元素，识别 v-model */
compileElement(node) {
const attrs = Array.from(node.attributes); // 获取元素绑定的所有属性
 attrs.forEach((attr) => {
if (attr.name.includes('v-')) {
// 判断是否为自定义的指令
 const value = attr.value; // 属性的值
 let type = attr.name.split('-')[1];
compileUtils[type](node, this.vm, value);
}
});
/* 编译文本，识别 {{}} */
compileText(node) {
const reg = /\{\{([^}]+)\}\}/g; // {{}} 正则表达式
 const value = node.textContent;
if (reg.test(value)) {
compileUtils['text'](node, this.vm, value);
}
}
}

5. 编译中使用的具体方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62


const compileUtils = {
/* 获取 data 中数据对应的值 */
getValue(vm, value) {
value = value.split('.'); // 所有的数据都是 data 的属性
 return value.reduce((prev, next) => prev[next], vm.$data);
}
/* 获取编译后的文本内容 */
getTextValue(vm, value) {
return value.replace(/\{\{([^}]+)\}\}/g, (...arguments) =>
this.getValue(vm, arguments[1])
);
}
/* 给数据设置新值 */
setVal(vm, value, newValue) {
value = value.split('.');
return value.reduce((prev, next, currentIndex) => {
if (currentIndex === value.length - 1) {
return (prev[next] = newValue);
}
return prev[next];
}, vm.$data);
}
/* v-model 处理*/
model(node, vm, value) {
const doUpdate = this.updater.modelUpdater; // 定义更新视图的方法
 new Watcher(vm, value, (newValue) => {
// 实例化一个观察者
 doUpdate && doUpdate(node, this.getValue(vm, value));
});
// 绑定 input 事件，输入值时更新数据
 node.addEventListener('input', (e) => {
const newValue = e.target.value;
this.setVal(vm, value, newValue);
});
}
/* 文本处理 */
text(node, vm, value) {
const doUpdate = this.updater.textUpdater; // 定义更新视图的方法
 const pureValue = this.getTextValue(vm, value); // 获取 {{}} 内的纯值
 value.replace(/\{\{([^}]+)\}\}/g, (...arguments) => {
// 实例化一个观察者
 new Watcher(vm, arguments[1], (newValue) => {
doUpdate && doUpdate(node, this.getTextValue(vm, value));
});
});
doUpdate && doUpdate(node, pureValue);
}
/* 更新 DOM */
updater: {
textUpdater(node, value) {
node.textContent = value;
},
modelUpdater(node, value) {
node.value = value;
},
},
};

6. 初始化 ZVue，添加代理

因为数据都挂载在了 $data 对象上，要访问需要通过 this.$data.name 方式访问，而要通过 this.name 方式访问需要添加一层代理，原理还是 Object.defineProperty：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


class ZVue {
constructor(options) {
this.$el = options.el;
this.$data = options.data;
if (this.$el) {
new Observer(this.$data);
this.proxyData(this.$data);
new Compile(this.$el, this);
}
}
/* 将 this.$data 上的数据代理到 this 上 */
proxyData(data) {
Object.keys(data).forEach((key) => {
Object.defineProperty(this, key, {
get() { return data[key] },
set(newValue) {
data[key] = newValue;
},
});
});
}
}

7. 实例化，挂载数据

1
2
3
4
5
6


const vm = new ZVue({
el: '#app',
data: {
name: 'Zander'
}
});

Vue3 扩展

"Bye Object.defineProperty!"²

Vue3 在数据劫持上选择了比 Object.defineProperty() 效率更高、性能更优的 Proxy。Proxy 对象的专属功能就是属性的查找、赋值、函数调用等，实例化时需要两个参数：

target：目标对象，可以是 Object、Array、Function 等类型。
handler：由处理函数组成的对象，处理函数是一系列操作目标对象时触发的钩子函数。

简单使用 Proxy 实现数据劫持：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


const obj = {
name: 'Zander',
age: 18,
hobbies: {
sport: 'running',
game: 'LOL'
}
}
const proxy = new Proxy(obj, {
get(target, propertyKey, receiver){ // 分别为需要取值的目标对象、需要获取的键值、当前 proxy 实例（可选）
 console.log(`读取了${propertyKey}属性的值`);
return Reflect.get(target, propertyKey, receiver); // 通过函数调用实现取值，详见 MDN
 },
set(target, propertyKey, value, receiver){ // 分别为设置属性的目标对象、属性名称、设置的值、当前 proxy 实例（可选）
 console.log(`设置了${propertyKey}属性的值`);
Reflect.set(target, propertyKey, value, receiver);
}
})
proxy.age; // log: 读取了age属性的值

proxy.hobbies.game = 'MineSweeper'; // log: 读取了hobbies属性的值

Proxy 的一些妙处：

Proxy 的监听目标是..整个对象..，而 Object.defineProperty() 一次只能操作..一个对象的一个属性..，要监听整个对象需要多层的迭代和递归。
Object.defineProperty() 无法监听..数组类型..属性的变化³，但 Proxy 🉑️。
可操作的钩子函数有 ..13.. 个之多。

References & Resources

将 HTML 模板转换为 AST 的过程，比如解析 Vue 中的 {{}} 语法。 ↩︎
见尤雨溪 Vue3.0 Updates 主题演讲 PPT。 ↩︎
Vue2 中的解决方法是重写数组的操作方法，详见 Github，但通过下标修改数组的情况仍无法监测。 ↩︎

MEVN 项目部署

xuezenghui6@gmail.com (Zander Hsueh) — Wed, 17 Jun 2020 16:13:25 +0800

前言

有一个计划已经躺在我的 Microsoft To Do 里许久了——“完成一个图片合成工具”，解释一下，这个工具的作用是合成图片（???还用你解释）。哈哈哈，因为在阅读技术文章的时候发现很多文章的配图为多个技术的 Logo 组成的架构图，尤其 Medium 中的文章，比如这个，这个，当然了，谁让我又偏爱 Medium 的风格呢，所以还有这个。那有没有一个方便的方式可以快速地生成这样瘠薄（技术博主）常用的图片呢？没找到……那就自己写一个罢。

功能开发上并不难，图片合成使用 canvas 实现，剩下就是各技术 Logo 的管理了，相当于一个简单的图床。5天，基本功能实现，传送门——Psoon，名字是 Picture synthesis soon，意为快速地 Ps 😳，技术架构为 MEVN¹，源码见我的 GitHub。

因为自己平常与开发以外的环节接触不多，Linux 和 Docker 也都只学了皮毛，整个项目下来问题就几乎都出在了部署上，比如 Vue 项目的部署问题：

字体文件太大，导致首屏加载时间极长
路由采用 History 模式，直接访问子路由或刷新页面导致 404
样式问题

但因为 Vue 项目的基本部署已在前文记录，这里就不详述了，针对上面几个问题会视其必要性辟文新立，先说说部署后台的主要工作。

部署方式

诚言，在服务器上裸机部署 Node.js + MongoDB 的 Web 应用是没有什么难度的，前文也有简单地记录过。为了更接近生产环境，也为了检测自己 Docker 的学习效果，决定采用 Docker 部署的方式。

简单说一下 Docker，它基于 Go 语言开发，是一个基于 Linux 容器虚拟化技术的用于构建、部署和共享应用程序的工具，做到了使 APP 及其运行环境“一次封装，到处运行”，大大避免了诸如“在我电脑上可以跑啊”之类的言论🌚，现如今 Docker 在后端的江湖地位也可谓举足轻重了。

环境安装

环境主要是 Docker 工具集的安装，这里介绍如何在 CentOS 8 中安装 Docker 及 Docker Compose，Docker Compose 是用于定义和运行多个容器的一个 Docker 子工具，多用于有关联关系的容器之间的联调部署，譬如 Express 应用和 MongoDB 之间的..通信互联..。

安装 Docker

Docker 分为社区版 Docker CE 和企业版 Docker EE，这里安装的为社区版。

1. 添加 Docker CE 存储库

1

$ dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo

2. 查看可安装的软件包版本

1

$ dnf list docker-ce

3. 安装最新版本的 Docker CE

1

$ dnf install docker-ce --nobest -y

4. 验证安装结果

1

$ docker --version

安装 Docker Compose

1. 安装 curl

1

$ dnf install curl -y

2. 下载安装 Docker Compose

1

$ sudo curl -L "https://github.com/docker/compose/releases/download/1.26.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

1.26.0 为截止文章撰写之日的最新版本，后续请关注 GitHub releases 及时更新替换版本。

3. 为下载的二进制文件添加可执行权限

1

$ sudo chmod +x /usr/local/bin/docker-compose

4. 验证结果

1

$ docker-compose --version

部署应用

创建 Dockerfile 文件

简单点说，使用 Docker 部署应用即运行相应的 Docker 容器，需要先创建容器，创建容器需要使用 Docker 映像，而要构建映像，就需要使用 Dockerfile。在 Node.js 应用根目录下创建 Dockerfile 文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# 基础映像
FROM node:latest

# 作者信息
MAINTAINER Zander<xuezenghui@gmail.com>

# 设定运行容器后终端所在的工作路径
WORKDIR /usr/src/psoon

# 拷贝依赖文件到映像文件夹
COPY package.json /usr/src/psoon/

# 安装依赖
RUN npm install

# 拷贝项目文件和目录到映像文件夹
COPY . /usr/src/psoon

# 暴露端口号
EXPOSE 2000

# 启动容器
CMD ["npm", "start"]

你可能会有疑问：复制全部文件不是已经包含 package.json 文件了吗？为什么要..执行两次.. COPY 命令？

原因是分作两步可以利用 Docker 的缓存层，防止每次更改应用程序源码后都重新构建 node_modules 模块，详参《把一个 Node.js web 应用程序给 Docker 化》。

创建 Docker Compose 文件

如果不使用 Docker Compose 则需要通过 Dockerfile 手动构建映像，再通过映像启动容器，而有了 Docker Compose 只需要创建用于启动容器服务的 Docker Compose 文件，同样的，在项目根目录下创建 docker-compose.yml 文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


version: "3.4" # Compose file 版本
services:
 psoon: # 服务名
 container_name: psoon # 容器名
 restart: always # 失败时重新运行容器
 build:
 context: . # 使用当前目录中的 Dockerfile 文件构建映像
 ports: # 主机和容器的端口映射
 - "2000:2000"
 links: # 链接的容器
 - mongo
 mongo:
 container_name: mongo
 image: mongo # mongo 使用官方映像
 volumes: # 指定容器数据卷，数据持久化
 - ./data:/data/db
 ports:
 - "27017:27017"

注：Node 和 MongoDB 暴露的端口服务器都要配置对外开放。

上传项目至服务器

本地创建好项目构建部署所需的文件后需要将项目上传至 CentOS 8，有些文章中建议建立一个 .dockerignore 文件，其作用与 .gitignore 类似，用来排除构建 Docker 映像时不需要的文件和目录，比如 node_modules、npm-debug.log 文件。但我这里项目文件是由本地上传至服务器，手动删除此类文件不上传至服务器即可（变相节省服务器内存???），个人理解 .dockerignore 文件应多作用于 CI/CD² 时。

1
2
3
4


# 项目根目录下起步执行
$ rm -rf node_modules
$ cd ..
$ scp -r psoon root@<公网 IP 地址>:/usr/src/psoon

构建镜像，启动服务

登录服务器后进入项目目录，执行 Docker Compose 的构建启动命令：

1
2


$ cd /usr/src/psoon
$ docker-compose up -d

-d 指定启动容器后不进入交互模式，以守护式进程运行。

构建过程：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


Building psoon
Step 1/8 : FROM node:latest
---> dcda6cd5e439
Step 2/8 : MAINTAINER Zander<xuezenghui@gmail.com>
---> Running in 9c2e8d8a4df1
Removing intermediate container 9c2e8d8a4df1
---> ab2f34e52d9f
Step 3/8 : WORKDIR /usr/src/psoon
---> Running in 184b939e4b09
Removing intermediate container 184b939e4b09
---> f16a6e357920
Step 4/8 : COPY package.json /usr/src/psoon/
---> 4e9485e1a306
Step 5/8 : RUN npm install
---> Running in ce459058cd8a
......
Removing intermediate container ce459058cd8a
---> c05c31eabb12
Step 6/8 : COPY . /usr/src/psoon
---> 66b86989d3ba
Step 7/8 : EXPOSE 2000
---> Running in 67332d77017b
Removing intermediate container 67332d77017b
---> fc863845b8a8
Step 8/8 : CMD ["npm", "start"]
---> Running in 022afc431683
Removing intermediate container 022afc431683
---> bacb1e3a5dd8
Successfully built bacb1e3a5dd8
Successfully tagged psoon_psoon:latest

在这里不得不提一个踩了一下午的坑🥶，在我执行 $ docker-compose up 命令后构建总是卡在 Step 5 RUN npm install 处，然后报错如下：

npm ERR! code EAI_AGAIN
npm ERR! errno EAI_AGAIN
npm ERR! request to https://registry.npmjs.org/connect-history-api-fallback failed, reason: getaddrinfo EAI_AGAIN registry.npmjs.org
npm ERR! A complete log of this run can be found in:
npm ERR! /root/.npm/_logs/2020-06-18T07_52_25_346Z-debug.log
ERROR: Service 'psoon' failed to build: The command '/bin/sh -c npm install' returned a non-zero code: 1

尝试更改 npm 镜像源、更改服务器 DNS 等等方法皆无效，最终解决方案为指定 Docker 容器的网络为 host，即宿主机的网络（默认为 bridge 网桥网络），具体方式：

手动构建镜像：

1

$ docker build . --network host

使用 Docker Compose 构建，则需要更改 docker-compose.yml 文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


version: "3.4" # Compose file 版本
services:
 psoon: # 服务名
 container_name: psoon # 容器名
 restart: always # 失败时重新运行容器
 build:
 context: . # 使用当前目录中的 Dockerfile 文件构建映像
+ network: host # 指定容器使用的网络
 ports: # 主机和容器的端口映射
 - "2000:2000"
 links: # 链接的容器
 - mongo
 mongo:
 container_name: mongo
 image: mongo # mongo 使用官方映像
 volumes: # 指定容器数据卷，数据持久化
 - ./data:/data/db
 ports:
 - "27017:27017"

成功后使用 $ docker images 和 $ docker ps 命令可查看构建成功的镜像和已经启动的两个容器，在浏览器中输入 IP:2000 或 IP:27017 也就能访问到相应的服务了😚。

最后，不要忘记在 NGINX 中配置接口请求地址～

References & Resources

MongoDB + Express.js + Vue.js + Node.js 技术架构。 ↩︎
持续集成、持续交付和持续部署。 ↩︎

"Updating Homebrew..."

xuezenghui6@gmail.com (Zander Hsueh) — Fri, 05 Jun 2020 09:30:55 +0800

问题

Homebrew 是 MacOS 下一个极为方便的包管理工具，但是国内在使用的时候往往由于网络环境的原因会出现这么一个问题——在执行 $ brew update 或 $ brew upgrade 等操作时，终端会卡死在 Updating Homebrew... 状态，导致无法更新/下载 Homebrew 和本地软件。

解决

和大多数网络问题导致的此类情况解决方法类似——要么..换源..，要么..科学上网..。

更换 Homebrew 源

换源算是最常规的解决办法了，像 Npm 换 cnpm 镜像、Docker 换阿里云镜像等等，Homebrew 的有效镜像推荐中科大开源软件镜像和清华大学开源软件镜像，以 USTC 镜像为例更换 Homebrew 源步骤：

1. 更换 brew 程序本身的源

1
2
3
4
5


$ cd "$(brew --repo)"
$ git remote set-url origin https://mirrors.ustc.edu.cn/brew.git
# 还原为官方源
$ git remote set-url origin https://github.com/Homebrew/brew.git

2. 更换 homebrew-core 源

1
2
3
4
5


$ cd "$(brew --repo)/Library/Taps/homebrew/homebrew-core"
$ git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git
# 还原为官方源
$ git remote set-url origin https://github.com/Homebrew/homebrew-core.git

homebrew-core 为 Homebrew 的核心软件仓库。

3. 更换 homebrew-cask 源

1
2
3
4
5


$ cd "$(brew --repo)"/Library/Taps/homebrew/homebrew-cask
$ git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask.git
# 还原为官方源
$ git remote set-url origin https://github.com/Homebrew/homebrew-cask.git

homebrew-cask 是提供 macOS 应用程序的软件仓库。

配置终端科学上网

一般只更换上述的三个源就可以解决 Homebrew 软件的下载和更新问题了，但是这并不是一劳永逸的办法。你是否在执行 $ git clone 时每秒几 kb 的下载速度？你是否在使用 Npm / Yarn 安装依赖时等得头大……

并且，因为终端只支持 HTTP 代理，而主机使用的是 Sock 代理，即便主机使用了代理工具可以科学上网，但终端的网络环境还是一样的糟糕，这时，就需要配置终端科学上网😎。Privoxy 代理工具可实现终端的 HTTP 代理，具体配置步骤：

在进行以下步骤前，请确保本机可以科学上网，因为 Privoxy 是一个..客户端代理工具..，单独不能进行翻墙。

1. 安装 Privoxy

1

$ brew install privoxy

2. 配置监听端口

1

$ nano /usr/local/etc/privoxy/config

追加配置内容：

1
2


listen-address 0.0.0.0:8118 # 监听8118端口
forward-socks5 / localhost:1080 . # 转发至socks端口

localhost 后的端口号为本机 Sock 监听端口，可在本机代理工具中查看，以 V2rayU 为例，进入偏好设置➡️Advance即可查看。

3. 启动 Privoxy 服务

1

$ sudo /usr/local/sbin/privoxy /usr/local/etc/privoxy/config

4. 查看网络连接状况

1

netstat -na | grep 8118

如打印以下内容即为端口监听成功：

tcp4 0 0 *.8118 *.* LISTEN
tcp4 0 0 127.0.0.1.8118 *.* LISTEN

5. 开启 Privoxy 代理

1
2
3
4
5
6
7


# 开启
$ export http_proxy='http://localhost:8118'
$ export https_proxy='http://localhost:8118'
# 关闭
$ unset http_proxy
$ unser https_proxy

至此，..当前..终端已经可以进行科学上网了，在执行以上开启代理命令的前后分别执行 $ curl cip.cc 可查看网络 IP 地址的变化。但只针对当前打开的终端有效，新建的终端窗口需要重复执行步骤5来开启代理，当然，是有便捷方法的——配置打开/关闭代理的快捷命令：

配置 Oh My Zsh 的配置文件：

1

$ nano ~/.zshrc

内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


function proxy_on() {
 export no_proxy="localhost,127.0.0.1,localaddress,.localdomain.com"
 export http_proxy="http://localhost:8118"
 export https_proxy="http:/localhost:8118"
 echo -e "已开启代理"
}

function proxy_off(){
 unset http_proxy
 unset https_proxy
 echo -e "已关闭代理"
}

然后使用 $ source ~/.zshrc 命令执行更改。

Oh My Zsh 这么棒的工具你不会没安装吧？Alright，如果没安装，使用的是默认的终端，配置 $ nano ~/.bash_profile，内容无异，source 命令的文件路径也作相应更改即可。

Bingo～现在，在终端输入 $ proxy_on 即可打开终端代理功能，$ proxy_off 即关闭🤟，问题得解～

Linux 的些个操作

xuezenghui6@gmail.com (Zander Hsueh) — Mon, 25 May 2020 13:28:59 +0800

记录使用 Linux 时的些个操作，CenteOS 8.0 下。

配置非 root 用户

直接使用 root 权限操作 Linux 是极为不安全的，也是非常不提倡的，应该为不同的角色配置不同的用户身份，可为用户配置一定的管理权限，在需要执行管理操作时输入 sudo 前缀即可拥有 root 的管理权限，具体步骤：

1. 使用 root 用户身份登录 Linux

1

$ ssh root@service_ip

2. 创建新用户

1

$ adduser zander

3. 配置新用户的密码

1

$ passwd zander

4. 配置管理权限

1

$ usermod -aG wheel zander

usermod 命令用于修改用户账号，-aG 选项为用户指定附加组，wheel 组是 CentOS 8 中默认存在的拥有特殊权限的群组，群组中的成员可使用 sudo 命令执行 root 权限的操作。

免密登陆

每次本机连接 Linux 都需要输入用户密码，这可真是糟透了，是个懒人没错:)。为本机和服务器配对 SSH 公私密钥即可实现免密登录，只需要一行命令：

1

$ ssh-copy-id -i ~/.ssh/id_rsa.pub username@service_ip

当然前提是你本机已经生成了公私钥文件，但都看到这儿了你怎么可能没有呢🤨！

Keep Alive

终端中通过 SSH 连接上 Linux 后，若几分钟内不使用会导致连接失活，原因是防火墙在一定时间内未监测到会话活动后会自动断开 SSH 连接。可配置本机 SSH，使本地每隔一段时间发送生命周期信号发送至服务器，防止连接失活。同样的，也可配置远程服务器，使其定时向客户端发送数据来保证持久连接。

方法一、配置客户端

1. 创建 ~/.ssh/config 文件

1

$ touch ~/.ssh/config

2. 配置该文件

1
2
3


Host *
ServerAliveInterval 60
ServerAliveCountMax 10

此配置表示客户端每分钟向所有已连接的服务器发送一次数据，发送10次后如果仍未收到响应则关闭该连接。

方法二、配置服务器

编辑 /etc/ssh/ssh_config 文件

1

$ sudo nano /etc/ssh/ssh_config

内容为：

1
2


ClientAliveInterval 60
ClientAliveCountMax 10

配置 Docker 命令不需加 `sudo`

Docker 守护进程默认由 root 用户掌管，其他用户使用 Docker 命令时必须加 sudo 才可成功执行。可添加配置 docker 用户组使得组内用户使用 Docker 时不需加 sudo 命令。

1. 添加 docker 用户组

1

$ sudo groupadd docker

2. 将用户加入用户组

1

$ sudo usermod -aG docker username

3. 重新登录，或切换用户组以更新权限

1

$ newgrp docker

添加 root 权限用户

1. 添加用户

1

$ useradd username

2. 修改密码

1

$ passwd username

3. 修改 sudoers 文件

1

$ visudo

添加以下内容：

1
2


# 用户/组 主机=(允许切换到哪些用户或组) 允许执行的命令
username ALL=(ALL) ALL

How 与 Why

xuezenghui6@gmail.com (Zander Hsueh) — Fri, 24 Apr 2020 09:23:13 +0800

最近有一个困惑，不是技术上的困惑，而是思想上的困惑——特别喜欢问「为什么」，特别想知道「为什么」。

无论是学习新技术的过程中还是解决问题的时候，只要技术点中有没听过不熟悉的，就想要去搞个明白，就算能力和时间有限，不能入木三分也要知其大概。这导致了什么结果呢？

最大的影响是..效率..，比如之前在同样技术难度水平上的一篇博文花不了几个小时就可以完成（一般2~6个小时），而现在，由于学习过程中不断去查找新东西，又在新东西中看到新东西，又去了解……一篇博客甚至花了三天时间。

仔细想了想，是什么时候自己变得过分地不求甚解，大概是从自己抛弃百度使用 Google 后逐渐演变的。可能你不太理解，举个例子，昨天我的 Npm 缓存损坏了，百度的搜索结果几乎全都是 CSDN、简书文章上的简单解决办法 $ npm cache clean --force（广告、与搜索内容不符等问题也就不说了），潦草几句。Google 的搜索结果讨论更多的则是「Why」，甚至因为原理上的东西在这里产生分歧和碰撞，是的，它引导你去了解更多、更本质的知识，而不是解决了就一了了之。

不是我崇洋媚外，因为在我看来技术没有国界，思想更没有；也不是我非要褒一贬一，我没有否定百度，只是我更喜欢 Google 的氛围；这也并不是个例，长久以来的现象才形成现在的..习惯..。再说回来，对于一个问题，只了解「How」真的就够了吗？远远不够，知其然定要知其所以然，可能自己的问题在于没能把握好「How」与「Why」的天平吧。

那何以使得只追求「How」体现在了百度上的现象化结果？大概因为：

GFW¹ 并不只是封锁了互联网，它阻碍的是技术的进步，禁锢的是思想的延伸💔。

Great Firewall。 ↩︎

图片预览

xuezenghui6@gmail.com (Zander Hsueh) — Wed, 22 Apr 2020 09:04:15 +0800

需求

今天来看一个挺常见的需求，上传图片时页面展示选择的图片，具体实现效果可以点击下面的「上传图片」按钮试试👇～（只能选择 .png 或 .jpeg 格式图片）

按钮设计源自 CodePen。

实现

HTML

首先是要使用的标签，上传文件需要用到 <input> 标签，并且指定属性 type 的值为 file。

既然是预览图片，那么还需要指定选择文件的类型，使用 accept 属性可以规定..期望..的文件类型，为啥是「期望」呢？因为这只表示触发控件后默认允许选中的文件类型，比如在 MacOS 上，刁钻的用户仍可以在唤出的选择文件窗口中通过选项➡️格式：所有文件来选择其它类型的文件上传👿：

这就要求在 JavaScript 中还要判断用户选择的文件类型是否合法，后面会说到，先指定期望的类型为 PNG 或 JPG 格式的图片。并且，使用 <input> 标签时常用的做法是与 <label> 标签合用并且设置 <input> 为不可见，这样做的好处有两点：

<input> 的样式不易调整，而 <label> 的样式可以为所欲为。
<label> 增加了 <input>的命中区域。

所以现在的 HTML 是这样的：

1
2


<input type="file" accept="image/png, image/jpg" id="inputFile">
<label for="inputFile">上传图片</label>

CSS

样式上要做的一点是隐藏 <input>，剩下的就完全自由化了：

1
2
3


input {
display: none;
}

另外，CodePen 上的各种按钮样式可真是美哭我了，比那些在线设计按钮样式的网站好太多了🤫，强烈安利。

JavaScript

到了功能实现的环节了，首先需要拿到选择图片的相关信息，在用户选择了文件时可以触发 <input> 的 change 事件，change 事件的参数内包含一个属性 files，其对应的值 FileList 是一个..类数组..，由一个个 File 对象组成，对象内存储着用户选择的文件的信息，比如名字、大小、类型等。

因为 <input> 有一个 multiple 属性，设置后可以选择多个文件，所以 FileList 的类型为类数组。

能获取到文件的类型就可以做我们上面说的校验文件合法性了：

1
2
3
4
5
6
7
8


document.getElementById('inputFile').addEventListener('change', handleChange, false);
function handleChange(e){
const fileList = e.target.files; // 文件对象类数组
 if(fileList[0].type !== 'image/png' && fileList[0].type !== 'image/jpeg'){ // 校验文件类型
 return console.log('文件类型错误');
}
}

接下来需要在页面中显示图片，需要一个展示图片的容器，当然也可以使用 JavaScript 直接插入到页面，但前者更容易设置图片的样式。显示图片有两种方式——FileReader 和对象 URL。

1. FileReader

FileReader 对象用来..异步..读取文件的内容，可读取的目标正是获取到的 File 对象。

1
2
3
4
5


const reader = new FileReader(); // 实例化对象
reader.readAsDataURL(fileList[0]); // 开始异步读取文件
reader.onload = function (e) { // 读取完文件后触发的函数
 document.getElementById('previewImg').src = e.target.result; // 将图片的 base64 编码赋值给容器的 src 属性
}

readAsDataURL() 方法可读取传入的 File 对象，读取完成后会触发 onload 事件，事件的参数中就包含图片的 base64 编码，然后将它设置为页面中用于展示图片的 <img> 标签的 src 属性，图片成功显示～

2. 对象 URL

对象 URL 指的是 window.URL.createObjectURL() 和 window.URL.revokeObjectURL() 方法，window.URL.createObjectURL() 方法同样可传入一个 File 对象，但是返回的并不是图片的 base64 编码，而是一个特殊的字符串¹，长这个亚子：

blob:null/1a92aff8-90a4-4421-966c-4b151078da0f

不管它叫啥，它只能由浏览器内部生成，将 <img> 标签的 src 属性设置成它也可以显示图片：

1

document.getElementById('previewImg').src = (URL || webkitURL).createObjectURL(fileList[0]);

(URL || webkitURL).createObjectURL() 为兼容写法。

结语

效果就不用再展示了，完整方法和上面炫酷按钮的案例源码都在我的 GitHub 中。那么到底要选择使用哪个方式呢？

首先，这两个 API 的兼容性都是差不多的，IE 10+ 和所有主流浏览器都支持。从性能上来说，FileReader.readAsDataURL() 是异步执行，而 createObjectURL() 是同步执行，而 Blob URLs 占用的内存比 base64 更小，所以总体来讲 createObjectURL() 占优，但其关闭标签页时才会释放内存，使用的时候应考虑是否要用 window.URL.revokeObjectURL() 方法手动释放内存。

References & Resources

W3C 称它为 Blob URLs，MDN 称它为 Object-URLs。 ↩︎

ECS 服务器配置及部署实践

xuezenghui6@gmail.com (Zander Hsueh) — Mon, 13 Apr 2020 16:24:34 +0800

前端切图仔终于在今天也有自己的服务器了😳（还不是趁着没满24岁再薅两把阿里的羊毛）——2G 单核 1M 带宽云服务 ECS ，再入门不过了，也是，自己本来就是用来入门的。所以呢，在此记录服务器从零配置到部署前端项目（Vue.js）和后端项目（Node.js）的过程～

前置工作

学生优惠真的是超划算了，想当年大学时学 Java 的室友就给我疯狂安利，当时的我还嗤之以鼻——“我一学前端的要那玩意儿干哈，用不上”，现在看来真是蛮香的了🤤，建议有闲钱的续他个十年八年的……

服务器呢建议购买云服务器 ECS 而不是轻量应用服务器——如果你也想和我一样从零开始配置服务器，完整地体会整个过程的话。服务器的预装环境笔者选择 CentOS 8.0 64位。

购买完成后关键的一步是设置实例密码，在阿里云控制台中的实例列表页面➡️实例的右侧更多➡️密码/密钥➡️重置实例密码，这个密码用于后续连接远程服务器，其他的配置如安全组规则等按照阿里云的文档来操作即可，确保开通了80和443端口。

还需要说明的是我本机操作系统为 macOS Catalina 10.15.3，以下操作都基于此。

连接服务器及目录说明

连接服务器

macOS 连接服务器实例是极为方便的，在阿里云控制台查看实例的公网 IP 地址，然后在终端中通过 SSH 连接远程实例并指定为 root 用户身份：

1

$ ssh root@<公网 IP 地址>

接着会要求输入实例的密码，当输出 Welcome to Alibaba Cloud Elastic Compute Service ! 时就成功连接上了 ECS 实例。

Windows 系统及其它环境可参考阿里云帮助文档。

Linux 目录说明

Linux 操作系统遵循 FHS 的标准，根目录下默认存在以下次级目录：

成功连接实例后位于 /root 目录下，使用 $ cd .. 命令可回到根目录，再使用 $ ls 就可看到上图中的目录了。

使用 $ pwd 命令可查看当前所处路径，$ ls 命令查看当前目录下的可见文件，$ cd 命令切换所处目录。

部署前端项目

安装 NGINX

为什么要使用 NGINX？因为前端项目是纯静态的资源，要大家都能通过浏览器去访问它，就需要一个 Web 服务器，NGINX 正是一个合适且优异的免费开源高性能 HTTP 服务器和反向代理服务器。实际上之前我司安排过 NGINX 的相关学习任务，但学习内容还是偏概念性，现在实践终于来了～

首先明确服务器版本为 CentOS 8，因为在 CentOS 8 中安装 NGINX 的方法与在 CentOS 7 中安装的有些差异，CentOS 8 中的默认软件包管理工具是 dnf，它是 yum 的下一代版本（但 CentOS 8 中没有直接弃用 yum），安装 NGINX 只需要一个命令：

1

$ dnf install nginx

因为我直接使用 root 用户身份登陆的服务器，所以安装命令不需要添加 sudo，设置非 root 用户身份并配置 sudo 特权可参考 Initial Server Setup with CentOS 8 或我的另一篇文章 Linux 的些个操作。

然后在浏览器中访问服务器的公网 IP 就可以看到 NGINX 的欢迎界面啦🎉：

管理 NGINX

其实我没想让这篇文章也成为 NGINX 的安装使用教程，无奈自己在这方面也几乎是小白，就权当作学习记录罢了……

Systemd 是 Linux 的自带系统工具，用来管理系统进程，若进一步学习推荐阮一峰老师的 Systemd 入门教程。NGINX 进程也是通过 Systemd 的命令来管理的，以下是常用的一些操作：

1. 停止运行 NGINX

1

$ systemctl stop nginx

2. 启动 NGINX

1

$ systemctl start nginx

3. 重启 NGINX

1

$ systemctl restart nginx

4. 在不停止运行的情况下重新加载配置

1

$ systemctl reload nginx

配置 NGINX

要部署的项目文件一般都位于 /var/www/ 目录下，先创建一个示例网站的目录：

1

$ mkdir -p /var/www/zander/html

-p 选项表示确保每个层级的目录都存在，不存在则自动创建。

也就是说，网站要显示的内容就取决于此目录下的文件，那文件呢？创建呗～我是比较习惯使用 nano 文本编辑器的，简单好用，先安装：

1

$ dnf install nano

然后创建网站主要内容的 HTML 文件：

1

$ nano /var/www/zander/html/index.html

在文件中加入内容，可以外部复制后在 nano 中使用 cmd + v 直接粘贴：

1
2
3
4
5
6
7
8
9


<html>
<head>
<title>Zander</title>
</head>
<body>
<h1>Hello, I am Zander!</h1>
<p>Welcome to my site.</p>
</body>
</html>

然后使用 control + x 关闭文件，nano 会提示是否保存内容，输入 y 后按 Enter 键确认保存。

Linux 中几乎所有的配置文件都位于 /etc 目录中，而 NGINX 的所有配置文件都位于 /etc/nginx/ 目录，/etc/nginx/nginx.conf 是 NGINX 全局配置文件，但 NGINX 服务中通常不止托管一个网站，当有多个网站时常用的做法是在 /etc/nginx/conf.d/ 目录下创建每个网站相应的配置文件，如：

1

$ nano /etc/nginx/conf.d/zander.conf

然后编辑配置的具体内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


server {
# 监听 ipv4 端口
listen 80;
# 监听 ipv6 端口
listen [::]:80;
# 项目文件根目录
root /var/www/zander/html;
# 默认显示页
index index.html index.htm index.nginx-debian.html;
# 地址，没有域名可先不设置，默认为公网 IP
server_name _;
# 请求的 URL 过滤
location / {
try_files $uri $uri/ =404;
}
}

还有关键的一步不能忽略，我在这块儿就被坑惨了😢，虽然全局配置文件中已经通过 include /etc/nginx/conf.d/*.conf; 引入了我们自己添加的配置文件，但其实全局配置中默认是存在一个 server 配置的，如果不删除这个配置它就会覆盖我们自定义的配置，所以，请无情地将 /etc/nginx/nginx.conf 文件中的 server { ... } 这段全部删掉。

修改完成后使用 $ nginx -t 可检查 NGINX 的各文件中是否有语法错误，然后使用 $ systemctl restart nginx 重启服务。

最后，快乐地在浏览器访问公网 IP 就可以看到网站的内容了：

部署 Vue 项目

上面..简单..介绍了一个 HTML 文件的部署，其实 Vue 项目部署的原理和这是完全相同的，两个基本的步骤：一、在服务器创建网站内容；二、配置 NGINX。

1. 打包上传 Vue 项目

因为 Vue CLI 基于 Webpack 构建，所以使用 Vue CLI 创建的项目默认都有一个打包构建的命令——$ npm run build，执行完后会生成一个 dist 目录，这个目录和上例中的 /var/www/zander/html 一样，都是用于存放网站的内容，不同的是现在需要将本地的这个文件上传到服务器的 /var/www/ 目录下（更常见的做法应是将代码存储仓库的项目上传至服务器部署，也就是在服务器上使用 Git）。

Linux 中的 scp 命令可用来传输文件，macOS 中也是可以直接使用的，将打包构建好的 dist 目录上传至服务器：

1
2


# 项目根目录下执行
$ scp -r dist root@<公网 IP 地址>:/var/www/vue-test

-r 表示复制目录，递归传输目录内所有的文件，: 后为服务器中的存放位置。

然后输入实例密码开始传输，传输过程如下：

# 传输过程
favicon.ico 100% 4286 136.5KB/s 00:00
index.html 100% 776 26.6KB/s 00:00
app.8aaa5807.css 100% 428 14.3KB/s 00:00
app.3b5b763e.js.map 100% 27KB 472.7KB/s 00:00
about.79329b10.js.map 100% 1350 43.2KB/s 00:00
chunk-vendors.ae64d4e9.js 100% 92KB 891.5KB/s 00:00
app.3b5b763e.js ` 100% 6073 186.9KB/s 00:00
about.79329b10.js 100% 455 14.7KB/s 00:00
chunk-vendors.ae64d4e9.js.map 100% 464KB 3.6MB/s 00:00
logo.82b9c7a5.png 100% 6849 213.9KB/s 00:00

2. 配置 NGINX

上传完成后在服务器中就能看到对应的目录文件了，如上面所说，NGINX 托管部署的每个网站在 /etc/nginx/conf.d/ 目录下都应有一个自己的配置文件，创建之：

1

$ nano /etc/nginx/conf.d/vue-test.conf

编辑内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


server {
listen 80;
listen [::]:80;
root /var/www/vue-test;
index index.html index.htm index.nginx-debian.html;
server_name _;
location / {
try_files $uri $uri/ =404;
}
}

server_name 仍保持默认则会..覆盖..之前的网站内容，即现在还是通过公网 IP 地址来访问部署的 Vue 项目。重启 Nginx 服务后部署成功，熟悉的页面😉：

部署后端项目

Node.js 项目部署到服务器的目的是让其持续提供 Web 服务，其实原理很简单，我们在本地启动项目就只能在本地访问，而在服务器部署后一是能保证项目..持续..运行，二是可通过 ..IP.. 来访问项目提供的 Web 服务。

安装 Node.js

CentOS 8 中..快捷..安装 Node.js 和其包管理工具 NPM 的方式有两种，从 CentOS 储存库安装或使用 NVM 安装，这里只介绍第一种方式。输入以下命令查看储存库中可安装的 Node.js 版本列表：

1

$ yum module list nodejs

应该是可以看到一个稳定版本（v10.x）和一个开发版本（v12.x），安装默认版本的 Node.js，同时 NPM 也会被自动安装：

1

$ yum module install nodejs

使用 $ node --version 可查看安装的 Node.js 版本。

安装 PM2

说是部署，其实就是在服务器上运行罢了，但主要保证的就是..持续..运行，所以还需要用到 PM2 进行进程守护以保证项目不间断运行。使用 NPM 全局安装 PM2：

1

$ npm install pm2 -g

鉴于篇幅原因此处不再详细介绍 PM2 具体使用方法，官方文档很清晰啦～

部署 Node 项目

使用 express-generator 简单起一个项目，将项目从本地上传至服务器，注意需要删掉 node_modules 文件夹不要上传：

1
2


# 项目的父级目录下执行
$ scp -r deploy-node root@<公网 IP 地址>:/opt/node-test

进入服务器的项目目录下安装依赖：

1
2


$ cd /opt/node-test
$ npm install

注意咯，现在还不能直接运行项目，因为项目的默认端口是 3000，但服务器的 3000 端口还没有对外开放，所以需要先去服务器管理控制台给实例添加一条 3000 端口的安全组规则。

然后使用 PM2 启动项目：

1
2


# 项目根目录下执行
$ pm2 start ./bin/www

最后，在浏览器输入 <公网 IP 地址>:3000 可访问到 Web 服务🎉：

References & Resources

图源《鸟哥的 Linux 私房菜》。 ↩︎

从浏览器工作原理探闭包

xuezenghui6@gmail.com (Zander Hsueh) — Tue, 31 Mar 2020 16:43:41 +0800

历时一个多月，终于学习完了早就应该掌握的浏览器工作原理知识¹，受益匪浅的地方主要在于两点：

从原理上理解了编程中常见的技巧及误区（知其然也知其所以然）
扩展了视野，能从更高更广的维度审视页面（百尺竿头更进一步）

闭包这个概念在前端眼中丝毫不陌生，倒不是因为它的使用率有多么高，而是它的运作和原理关联到了 ECMAScript 的多个概念，如作用域、作用域链、GC² 等，恰恰如此，它也是前端面试中必不可少的考点，同时也是被大家讲烂了的东西。那为什么我还要写？因为从底层的角度来窥探闭包的真面目简直不要太清晰😎。

作用域

要说闭包就要说到作用域链，而要说作用域链就要说说作用域了。

作用域指在程序中定义变量的区域，而这个区域决定了变量的生命周期。换句话说，作用域控制着变量和函数的可见性和生命周期。

ES6 之后 JavaScript 有三种作用域：

1. 全局作用域

全局作用域即使用 var 定义的变量³，在代码中任何地方都可以访问到，它的生命周期就是整个页面的生命周期。

2. 函数作用域

函数作用域就是定义在函数内部的变量或函数，而且定义的变量和函数只能在函数内部访问，函数执行结束后这些变量都会被销毁。

3. 块级作用域

块级作用域就是使用一对大括号包裹的区域，如函数、判断语句、循环语句等都是块级作用域，块级作用域中的变量和函数只能在其内部访问使用。而 ES6 之前只能使用 var 定义变量，并不支持块级作用域：

1
2
3
4
5


var a = 1;
{
var a = 2;
}
console.log(a); // 输出2

ES6 中加入了 let 和 const 关键字，JavaScript 才终于有了块级作用域，才得以解决变量提升带来的种种问题✌：

1
2
3
4
5


var a = 1;
{
let a = 2;
}
console.log(a); // 输出1

作用域链

在我最早学习 JavaScript 的时候看到了一个很贴切的例子，至今还躺在我的笔记本里，是这么解释作用域链的：

假如你家四世同堂，你、你爸爸、你爷爷、你太爷爷，这时候你需要一笔钱买辆车，当然你自己是没有的😑，于是你问你老爸要，你老爸没有，然后又问你爷爷要，你爷爷也没有，最后问你太爷爷要，你太爷爷也没有，那就是真没有了。

例子中需要的「钱」就是作用域中的变量，而一代一代的关系指的是内外嵌套的作用域关系，递进的..链式结构..即是作用域链。的确，对于最粗浅的函数嵌套函数式的作用域链来说以这个例子来辅助理解是合理的，但是如果碰到了这样的情况就需要结合底层原理解释了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


function bar() {
console.log(myName);
}
function foo() {
var myName = "Tom";
bar();
}
var myName = "Zander";
foo();

来分析一下当执行到 bar() 函数时整段代码的调用栈⁴情况：

可以看到执行到 bar() 函数内部时两个地方存在 myName 变量——foo() 函数的执行上下文⁵中和全局执行上下文中，那么 bar() 中要输出的 myName 应该选择哪个呢？

当代码中使用一个变量时，会先在当前的执行上下文中查找该变量，比如上例中会先在 bar() 函数内部查找是否存在 myName，显然是没有的。但是，在每个执行上下文的变量环境中都存在一个外部引用 outer，outer 总是指向当前执行上下文的..外部..执行上下文，如果在当前的执行上下文中没有找到需要的变量会沿着 outer 所指向的执行上下文继续查找，上例中的「外部执行上下文」即全局上下文，所以 myName 即为 Zander，而这个通过 outer 连接的链条就是作用域链。

但为什么 bar() 是在 foo() 函数内部执行的还访问不到 foo() 函数中的变量呢？这是因为词法作用域的存在：作用域是由代码中函数声明的位置决定的，和函数在什么时候调用是无关的，按照声明时的结构，内部函数可以访问外部函数中的变量。

为了更进一步理解，改变一下代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
function bar() {
console.log(myName);
}
function foo() {
var myName = "Tom";
bar();
}
let myName = "Bob";
}
var myName = "Zander";
foo();

这里通过一对大括号创建了一个块级作用域，块级作用域中通过 let 关键字又定义了一个 myName，此时，bar() 和 foo() 的函数执行上下文中的 outer 指向的就是这个..外部..的块级作用域的执行上下文了，块级作用域的执行上下文中的 outer 才指向的是全局执行上下文，所以 bar() 的输出结果为 Bob（不信你删掉 let 那行试试结果是不是 Zander😛～）。

需要注意的是通过 let 和 const 定义的变量会存放于执行上下文的..词法环境..中，而在一个执行上下文中查找变量的规则是：先沿着词法环境的栈顶向下查询，找到则返回，找不到则继续在变量环境中查找。

闭包

先来看段代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


function foo() {
var name = 'Zander';
function bar() {
console.log(name);
}
return bar;
}
console.log(name); // 报错：name is not defined

var hello = foo();
hello(); // 输出：Zander

根据作用域及作用域链的概念就可知 foo() 函数外获取不到函数内定义的 name，所以第一个输出会报错，那为什么同样是在函数外部的 hello() 可以获取到 name？因为闭包（closure）的存在。

宏观角度

从宏观角度来看，产生闭包的本质有两点——词法作用域和函数当作值传递，函数当作值传递很简单，就像上面代码中 foo() 函数将 bar() 这个内部函数当作值返回了，此时，这个返回的值就相当于一个可以访问这个函数【bar()】词法作用域中的变量【name】的通道，通过这个通道获取到的所有变量就是闭包。

换言之，当一个外部函数返回一个内部函数后，即使外部函数执行结束了，内部函数中使用的外部函数的变量依然保存在内存中，把这些变量的集合就叫做闭包。

举个例子，我家花钱的方式是我妈让我去买菜，而且我家只买菜，也就是说如果别人想拿到我家的钱，就得我妈让我去买菜，然后从我这里拿到我家的钱。

「我家」就是一个局部作用域，「钱」就是作用域中的内部变量，外部只能通过「我」这个作用域中返回的函数来获取作用域中的内部变量。

微观角度

上面的文字可能还是比较晦涩，那就从底层原理的角度再分析，当执行到 return bar 时调用栈是这样的：

词法作用域规定内部函数总是可以访问外部函数的变量，所以任何时候在 bar() 函数中都可以获取到 name，正因为如此，当把 foo() 函数的执行结果 bar 赋值给 hello 时，虽然 foo() 函数已经执行完毕，但其内的变量 name 并没有被销毁掉，仍可以通过 bar 直接或间接访问。foo() 函数执行完后调用栈情况：

当 foo() 函数执行完后其执行上下文就会从调用栈弹出，但 name 变量还保存于内存中，特殊的是，只能通过 foo 返回的 bar 才能访问它。可以通过 Chrome 开发者工具的 Soures 面板打断点来查看闭包：

闭包在作用域链中所处的位置也很明显：Local（当前执行上下文）➡️Closure（闭包）➡️Global（全局执行上下文）。

内存泄漏

与闭包常常一同谈起的还有一个词——内存泄漏，内存泄漏是指不再使用的变量没有及时地释放，内存没有合理地被回收。但其实在现代浏览器中闭包通常不会导致内存泄漏，只有..滥用..闭包使得很多变量都被保存在内存中无法释放才容易导致内存泄漏。

合理使用闭包，从容应对面试～

具体的学习内容是极客时间的浏览器工作原理与实践课程，需要资源请留言。 ↩︎
Garbage Collecation，垃圾回收机制。 ↩︎
虽然不使用任何关键字定义的隐式全局变量也存在于全局作用域，但这种“野路子”并不在考虑范畴之内，原因参 MDN。 ↩︎
Call stack，用来管理函数调用关系的一种数据结构。 ↩︎
执行上下文是 JavaScript 执行一段代码时的运行环境。 ↩︎

用 GraphQL 玩 GitLab API

xuezenghui6@gmail.com (Zander Hsueh) — Thu, 12 Mar 2020 10:26:14 +0800

其实这篇文章的题目让我纠结了许久，在我浅显地看了 GraphQL 和 GitLab API 之后我司终于布置了相关的开发任务，这才发觉「纸上得来终觉浅」。没错，这更偏向于是一篇 GraphQL + GitLab API 的实践，也算是 Vue Apollo 的一个进阶和 GitLab API 的一次扩展。总之，这次实践既打破了自己之前文章中的一些观点（打脸），也是对之前知识点的一个补充，更是记录自己第一次的 GraphQL 从理论到实战🤟。

项目初始化

客户端

Vue 中采用 Vue Apollo 来集成 GraphQL 服务，安装使用 Vue Apollo 的方式有三种：

1. Vue CLI 插件

Vue Apollo 的开发者 Guillaume Chau 制作的 Vue CLI 插件，一行命令就可安装 Apollo——$ vue add apollo，安装成功后 Apollo 的相关配置都位于自动生成的 vue-apollo.js 文件中，需要做的配置可参考此文。

2. Apollo Boost

1

$ npm install --save vue-apollo graphql apollo-boost

一种折中的安装方式，apollo-boost 中包含了 Apollo 的一些核心包：

apollo-client：Apollo 客户端
apollo-cache-inmemory：官方推荐的缓存包
apollo-link-http：用于通过 HTTP 链接获取 GraphQL 服务器的数据
apollo-link-error：用于检查和处理 GraphQL API 的错误
graphql-tag：用于在 JavaScript 中使用模版字符串的方式编写 GraphQL 查询

安装成功后只需要在 main.js 中添加一个 ApolloClient 实例来指定 GraphQL 入口：

1
2
3
4
5


import ApolloClient from 'apollo-boost'
const apolloClient = new ApolloClient({
uri: 'https://git.zander.com/api/graphql'
})

此处的 uri 为示例 GitLab API 请求入口，如果你有 GitLab 账号可先参考此文章进行 GitLab 授权认证的相关操作，但是有一个坑点是需要注意的，GitLab Application 的回调地址中..不能..有 # 符号，冲突在于 Vue 中如果使用 hash 模式的 Vue Router 则路径中必定包含 # 符号，所以在创建 Vue 项目时应采用 History 模式的路由。

3. 自行安装

没错，就是把 Apollo Boost 中包含的所有包及其它依赖包手动安装：

1

$ npm install --save vue-apollo graphql apollo-client apollo-link apollo-link-http apollo-cache-inmemory graphql-tag axios

其中 apollo-link 是发送 GraphQL 请求或者获取 GraphQL 数据时的中间件，可进行请求的授权、错误处理等，是 apollo-link-http 的依赖包。axios 就不用多说了哈～

为了更清晰地明确各个配置项的作用，这次呢，就手动安装相关依赖，然后进行相关的配置：

首先建立一个与 main.js 同级的 Apollo 配置文件 vue-apollo.js：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


import { ApolloClient } from 'apollo-client';
import { createHttpLink } from 'apollo-link-http';
import { InMemoryCache } from 'apollo-cache-inmemory';
import VueApollo from 'vue-apollo';
import Vue from 'vue';
Vue.use(VueApollo);
// 连接 GraphQL 服务
const httpLink = createHttpLink({
uri: 'https://git.zander.com/api/graphql',
})
// 实现缓存
const cache = new InMemoryCache();
// 创建 Apollo 客户端
const apolloClient = new ApolloClient({
link: httpLink,
cache,
})
// 创建用于挂载到所有组件中的 Apollo 客户端实例
const apolloProvider = new VueApollo ({
defaultClient: apolloClient,
})
export default apolloProvider;

在 mian.js 中导入并挂载到 Vue 中

1
2
3
4
5
6
7


import apolloProvider from "./vue-apollo";
new Vue({
router,
apolloProvider,
render: function (h) { return h(App) }
}).$mount('#app')

由于 Apollo 的生态实在庞大，不夸张地说，apollo-cache-inmemory、apolo-link 等任意一个模块拉出来分析都可以成为长篇大论，本文就只以应用的层面进行实践，要想了解更多建议研读 Apollo 官网，当然，文章中传送门也是很贴心的😎。

服务端

了解 GitLab API 的你一定知道为什么需要服务端了——授权，虽然要使用基于 GraphQL 的 GitLab API，但是它的授权与认证方式还是不变的，授权认证原理请参考此文。

使用 express-generator 搭建服务端，安装用于发送请求的依赖¹：

1

npm install --save request request-promise

授权与认证

准备工作做好了，接下来开始玩 API 了，授权还是第一步，先来说下思路：

在进入展示 GitLab 数据的页面时判断 localStorage 中是否有请求 GitLab API 所需要的 Access Token；
有 Token 则直接进行 GraphQL 查询并展示数据；
没有 Token 则询问是否去 GitLab 授权（肯定是咯🤷‍♂️）；
前往 GitLab 授权页面授权，拿到用于获取 Token 的 code；
返回数据展示的页面，获取 Token，进行 GraphQL 查询并展示数据。

服务端

1. 用于返回 GitLab 授权 URL 的接口

GitLab 授权页面的 URL 需要后端返回给前端，这样便于 GitLab Applications 的管理（不用在前端改授权 URL 的参数了），这个接口很容易，只是简单的字符串拼接：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


/* GET 获取授权 URL */
const APP_ID = "..."; // GitLab 应用 ID
const REDIRECT_URI = "http://localhost:8080/data"; // 重定向 URI
const STATE = "Zander"; // 用于确认请求的字段
const SCOPE = "api"; // 权限

router.get('/codeRequestUrl', (req, res) => {
if (req.query.state !== STATE) {
return res.json({
status: 501,
msg: "非法访问"
});
}
const url = `https://git.zander.com.cn/oauth/authorize?client_id=${APP_ID}&redirect_uri=${REDIRECT_URI}&response_type=code&state=${req.query.state}&scope=${SCOPE}`
res.json({
status: 200,
result: url
})
})

2. 用 code 获取 Access Token 的接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


const rp = require('request-promise');
const url = "https://git.zander.com.cn/oauth/token"; // 获取 Access Token 的请求 url 地址
const SECRET = "...";
router.post('/token', async (req, res) => {
const code = req.body.code;
const bodyData = {
client_id: APP_ID,
client_secret: SECRET,
code,
grant_type: "authorization_code",
redirect_uri: REDIRECT_URI
}
const options = {
url: url,
method: "POST",
headers: { //设置请求头
 "content-type": "application/json",
},
body: bodyData,
json: true
}
rp(options)
.then(data => {
return res.json({
status: 200,
result: data
});
})
.catch(err => {
return res.json({
status: 501,
msg: err.message || '请求出错'
})
})
});

客户端

👌，现在就没服务端啥事儿了，专心做一个页面仔，按照上面的思路来吧～

1. 获取 Access Token

首先 Access Token 是存于 localStorage 中的，需要判断其是否存在。优先考虑不存在的情况，也就是用户第一次进入页面时，需要在 mounted 钩子函数中判断，但是——只判断有没有 Token 就够了吗？如果用户完成了 GitLab 授权自动返回的页面（Redirect URI）还是此页面，那还没等用返回的 code 换 Token 呢就又被拉去授权了，就会陷入死循环，所以判断有没有 Token 的同时还需判断有没有 code，总结一下：

有 Token，发请求，拿数据（已经授权过了也存入 Token 了）
没 Token 也没 code，去授权，拿 code，换 Token（第一次进入页面）
没 Token，有 code，换 Token（刚从授权页面返回）

核心代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


<template>
<button @click="goToAuthorize">前往授权</button>
</template>
<script>
export default {
mounted() {
this.getToken();
},
methods: {
// 获取 Access Token
 async getToken() {
const apolloToken = window.localStorage.getItem("apollo-token");
if (!apolloToken && !this.$route.query.code) { // 没有 Token 也没有 code
 this.dialog = true;
return;
}
if (this.$route.query.code) {
const { data } = await this.$axios.post('/api/token', { code: this.$route.query.code });
if (data.status === 200 && data.result.access_token) {
window.localStorage.setItem('apollo-token', data.result.access_token);
} else {
console.log('获取 Access Token 失败');
}
}
},
// 获取请求 code 的 url
 async goToAuthorize(){
this.dialog = false;
const params = { state: "Zander" };
const { data } = await this.$axios.get('/api/codeRequestUrl', { params });
if (data.status === 200) {
location.href = data.result;
}else {
console.log('获取 url 失败');
}
}
}
}
</script>

2. 使用 Access Token

在配置文件 vue-apollo.js 中给 GraphQL 请求加入 Header：

1
2
3
4
5
6
7
8
9


// 获取 GitLab API Token
++ const apolloToken = window.localStorage.getItem('apollo-token');
const httpLink = createHttpLink({
uri: 'https://git.zander.com.cn/api/graphql',
++ headers: {
++ Authorization: `Bearer ${apolloToken}`
++ }
})

使用 GitLab GraphQL API 获取数据

如果基本了解 GraphQL 你就会知道，只要有了一个东西，API 使用起来就跟玩似的——GraphiQL，也就是 GraphQL 的 Playground，因为你的所有 GraphQL 接口文档都位于 Playground 中的 Docs 中。这也是 GraphQL 的一个重要特点和魅力体现吧——API 文档完全依赖于代码生成，而不是由开发人员自我发挥。

GitLab GraphQL API 的 Playground 主要依赖于你的 GitLab 网址，比如 https://git.zander.com.cn/-/graphql-explorer，只需替换中间的 url 为你的 GitLab url 即可，当然，你也可以先在这里体验一下～

查询数据

是的，..数据的查询方式..就是和之前记录的内容有出入的地方，先来康康此实例中的数据查询步骤：

1. 编写 gql 查询

src 目录下新建 /graphql/queries.js 文件，引入 gql，使用模板字符串语法编写查询语句：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


import gql from 'graphql-tag' //引入graphql
const queriesAPI = Object.create(null);
queriesAPI.project = gql`
 query project($fullPath: ID!){
 project(fullPath: $fullPath){
 id,
 issues{
 nodes{
 title
 author{
 name
 }
 createdAt
 labels{
 nodes{
 title,
 color
 }
 }
 }
 }
 }
}
`
export default queriesAPI;

GitLab GraphQL API 中的大部分查询都需要 fullPath 参数，即你 GitLab 中的项目地址，如项目完整的 url 为 https://git.zander.com.cn/ZanderXue/gitlab-api-test，fullPath 即为 ZanderXue/gitlab-api-test，问题是没有用来获取全部 fullPath 的接口，所以这个 fullPath 参数可能需要手动管理了。

2. Vue 组件中执行查询

先引入定义好的查询语句：

1

import queriesAPI from "../graphql/queries";

整个 Vue 中都可以使用 apolloProvider 中的全局对象 $apollo，它是连接 Vue 和 Apollo 的桥梁。比如现在需要执行的查询功能，可使用 this.$apollo.query() 方法：

1
2
3
4
5
6
7
8


async getData(){
const res = await this.$apollo.query({
query: queriesAPI.project,
variables: {
fullPath: 'ZanderXue/gitlab-api-test'
}
})
}

方法中的 query 参数为 GraphQL 查询语句，variables 参数是一个参数对象，更多参数可参考 Vue Apollo 智能查询。

一些问题

踩坑

在实践过程中发现的 GitLab GraphQL API 的数个坑点：

1. GraphQL 的查询默认只能嵌套三层，多于三层则报错

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


project(fullPath: "ZanderXue/gitlab-api-test"){
 issues{
 nodes{
 notes{
 nodes{
 discussion{
 notes{
 nodes{
 author{
 name
 }
 }
 }
 }
 }
 }
 }
 }
}

1
2
3
4
5
6
7


{
"errors": [
{
"message": "Recursive query - too many of fields '{\"nodes\"=>3}' detected in single branch of the query"
}
]
}

报错内容如上，这也引出了新的问题——错误捕捉及处理，下文会详述 Apollo 的错误处理，但三层嵌套的问题暂无解决方法，只能尽量避免😢。

2. 数据中如果某字段没有值，那么那一整条数据都会为 null

比如获取 project 中参与 issue 评论的用户的头像 url，如果用户没有主动设置头像（使用 GitLab 默认头像），那么用户的其他信息也将获取不到

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


project(fullPath: "ZanderXue/gitlab-api-test"){
 issues{
 nodes{
 notes{
 nodes{
 author{
 name,
 username,
 avatarUrl
 }
 }
 }
 }
 }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


{
"data": {
"project": {
"issues": {
"nodes": [
{
"notes": {
"nodes": [
null,
null,
{
"author": {
"name": "ZanderXue",
"username": "zander.xue",
"avatarUrl": "/uploads/-/system/user/avatar/249/avatar.png"
}
}
]
}
}
]
}
}
}
}

恕我直言，这一设计真的是有些蠢……只能放弃显示用户头像的需求了，不然难道要求用户必须设置头像😒？

3. url 路径问题

估计你也注意到了，上面 avatarUrl 的路径是不完整的，缺少 fullPath。不仅如此，所有的图片、文件、链接的路径都是不完整的，导致获取到数据后还需要做二次处理。

比如我的开发任务中，需要在页面渲染所有的 issue 评论，要用到 notes 中所有的 bodyHtml 字段（String 类型），就需要把字符串中所有 a 标签的 href 属性拼接完整，所有 img 标签的 src 属性拼接完整……哦对了，img 标签返回的是 base64 编码，当然，也是不完整的²🙂，还要将 src 属性中的路径替换成 data-src 的路径再拼接完整。

4. Access Token 过期处理

GitLab GraphQL API 目前无法对非法或过期的 Access Token 做出对应的反应（如返回不同的状态码或返回错误），而只是让 API 返回的数据为 null，原因是 GraphQL 的 resolve 函数只能返回固定的 Type 的数据，除非是 GraphQL 类型的错误才可直接返回相应的 error 信息。

因此解决方案只能从返回的数据入手了，比如判断是否为 null，是 null 则重新获取 Access Token。

进阶

1. 错误捕捉及处理

apollo-link-error 用来捕捉和处理 GraphQL 类型的错误（GraphQLErrors）或网络类型的错误（newworkErrors）。

安装：

1

$ npm install --save apollo-link-error

在 vue-apollo.js 文件中引入并配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


import { onError } from 'apollo-link-error';
const errorLink = onError(({ graphQLErrors, networkError }) => {
if (graphQLErrors)
for (let err of )
graphQLErrors.forEach(({ message, locations, path }) =>
console.log('GraphQL 类型的错误处理');
);
if (networkError) console.log('网络类型错误的处理');
});
const apolloClient = new ApolloClient({
link: errorLink.concat(httpLink),
cache,
})

onError 函数的参数对象包括以下五个属性：

GraphQLErrors：GraphQL 服务端错误，数组类型
networkError：网络类型的错误
operation：发生错误的操作
forward：一个方法，可以传入 operation，表示重新执行这次错误的操作
response：接口返回的结果

官方示例中表示可以利用 apollo-link-error 检测出认证相关的错误并进行相关处理，但是我尝试了下，Access Token 非法或失效..并没有..被捕捉到并认定为 GraphQLErrors，所以我暂且将其归类到「踩坑」标题下，该模块还需要进一步学习从而完善本文。

🎱案例 GitHub 地址：GitLab-GraphQL-API

request 已被弃用，此处使用 request-promise。 ↩︎
StackOverflow 上也有人提出此问题。 ↩︎

JSON Web Token

xuezenghui6@gmail.com (Zander Hsueh) — Mon, 02 Mar 2020 05:29:45 +0800

前言

几乎任何的现代商用网站都离不开..用户认证..，先来一段 Rap 解释一下用户认证——你说你是客户端，名叫小憨憨，你问服务端怎么看，它说这事儿必须验，你证明了自己有点儿憨，它把数据放心传……🤤也就是说，认证是为了保证服务端把数据安全、正确地传递给客户端。

身份认证的方式有基于 Cookie 的认证，如 Session，还有基于 Token 的认证，最著名也是最常用的就是 JSON Web Token（简称 JWT）了。

JSON Web Token

首先要明确的还是概念，JSON Web Token 并不是一项依赖于哪个编程语言的技术，而是一套开放的标准（RFC 7519），是一种技术实现的规范，依赖 JWT 思想规范的各种库才是具体的技术实现，如 jsonwebtoken、express-jwt 等。JWT 定义了一种简洁且独立的方式，用于在客户端和服务端之间安全地传输 JSON 格式的数据。

JWT 原理

客户端用户使用用户名和密码通过 POST 请求登录或注册
服务端确认用户合法，生成一个 JWT
将 JWT 返回给客户端，客户端将其保存在本地（一般保存在 localStorage 中）
之后客户端向服务端发送 HTTP 请求需要将 JWT 加入请求头中
服务器解析 JWT，检查是否合法且有效
根据检查结果对客户端做出响应

JWT 结构

服务端生成的 JWT 是一段很长的字符串，由三部分组成，分别为 Header（头部）、Payload（负载）和 Signature（签名），中间用.分隔：

1. Header

头部 Header 是经过 Base64Url¹ 编码的 JSON 对象：

1
2
3
4


{
"alg": "HS256",
"typ": "JWT"
}

其中，alg是 JWT 所使用的签名算法，默认为HS256，typ即 Token 的类型。

2. Payload

负载 Payload 是一个包含传递数据的 JSON 对象，同样经过了 Base64Url 编码，包含以下可选属性：

iss：发行人
sub：主题
aud：受众群体
exp：到期时间
nbf：生效时间
iat：签发时间
jti：JWT ID

详情请参考 Registered Claim Names。

Payload 中的属性也可以自行添加，但由于 JWT 的内容对任何人都可见，除非对 JWT 进行二次加密，否则不能将任何机密的数据写入其中。

3. Signature

Signature 签名操作是在获取到了 Header 和 Payload 后进行的，比如 Header 中指定的是 HS256 算法，那么会通过以下方式创建 Signature：

HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secret)

其中的secret为保存在服务端的密钥，一般需要定期更新。完成签名后就将这三部分拼接在一起返回给客户端：

1

JWT = `${Header}.${Payload}.${Signature}`;

NodeJS 中实现 JWT

JWT 在各种语言中都有实现，如 java-jwt、angular2-jwt、go-jwt-middleware 等，更多的实现可在 auth0-docs 中查看，此处以 NodeJS 中的实现 jsonwebtoken 为例进行用户的认证。

初始化项目

先使用 express-generator 创建项目，安装需要的依赖：

1

npm install mongoose jsonwebtoken --save

连接 MongoDB 后添加 users 集合的数据库模型：

1
2
3
4
5
6
7
8
9


const mongoose = require('mongoose');
const Schema = mongoose.Schema;
const userSchema = new Schema({
"username": { type: String, required: true },
"password": { type: String, required: true },
});
module.exports = mongoose.model("User",userSchema, "users");

生成 JWT

为了更好地复用，完成一个公共的生成 JWT 方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


const jwt = require('jsonwebtoken');
const secret = "zander";
function createJWT(username, sub, exp, strTimer) {
const jwt = jwt.sign({
user: username, // 用户名
 sub: sub // 主题
 }, secret, {
expiresIn: `${exp}${strTimer}` // 过期时间
 })
return jwt;
}

1. 注册接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


router.post('/register', async (req, res) => {
const { username, password } = req.body;
const userData = { username, password };
const saveData = await new User(userData).save();
const jwt = createJWT(username, 'register', 1, 'h');
res.json({
status: 200,
data: saveData,
token: jwt
})
})

使用 Postman 测试接口：

2. 登录接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


router.post('/login', async (req, res) => {
const { username, password } = req.body;
const userData = await User.findOne({ username, password });
if (!userData) {
return res.json({
status: 501,
msg: '登录信息有误'
})
}
const jwt = createJWT(username, 'login', 5, 'd');
res.json({
status: 200,
data: userData,
token: jwt
})
})

验证 JWT

服务端生成了 JWT 后不保存，直接发送给客户端，而客户端拿到了 JWT 后将其保存下来，在发送其它请求时需要将 JWT 加入到请求头中：

Authorization: Bearer <token>

然后服务端验证 JWT 是否合法且有效：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


// 验证token方法
function verifyJWT(token) {
let decoded;
try {
decoded = jwt.verify(token.split(" ")[1], secret);
} catch (err) {
return err.message;
}
return decoded;
}
// 根据用户名获取密码接口
router.get('/password', async (req, res) => {
const token = req.headers['authorization'];
const { username } = req.query;
if (!token) {
return res.json({
status: 501,
msg: 'Not authorized'
});
}
const info = verifyJWT(token);
if(typeof info === "string"){
return res.json({
status: 501,
msg: info
});
}
const userData = await User.findOne({ username });
res.json({
status: 200,
data: userData.password
})
})

References & Resources

Base64Url 算法将 Base64 编码中的特殊字符替换为不影响在 URL 中传输的字符。 ↩︎

叹，漫漫

xuezenghui6@gmail.com (Zander Hsueh) — Sun, 12 Jan 2020 03:32:06 +0800

脱襁入世已半载，

时捉襟来时也慷慨。

友常欢，小君贤，

何事尤能惹卿烦？

操劳操劳几多得，

庆年少，叹前路漫漫，无心快活。

MongoDB bulkWrite() 实操

xuezenghui6@gmail.com (Zander Hsueh) — Fri, 10 Jan 2020 09:17:05 +0800

需求

一切技术都只是实现需求的载体，先不开门见山，来看一个实际项目中遇到的需求：

要求多选后点击计算按钮发送请求，更新 MongoDB 数据库员工集合中每个所选员工文档的一个字段，而每个文档这个字段要更新的目标值都是..个性化..的，比如 Leon 的这个字段要更新为 500，Paul 的要更新为 999，Zander 的要更新为 100。

能为此次数据库操作提供的数据是这样的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


const data = [
{
name: 'Leon',
value_index: 500
},
{
name: 'Paul',
value_index: 999
},
{
name: 'Zander',
value_index: 100
}
];

实现

以下操作数据库的方法都是 MongoDB 提供的，Mongoose 实际是进行了移植和支持，两者原理及实现方式相同，为究其本质、探其实操，实例代码使用的是 Mongoose。

你可能会想到使用updateMany()，它支持将多个 Document 的字段更新为..同一个值..或者按照..相同的条件..来更新：

1
2
3
4
5
6
7
8


Employee.updateMany(
{
"name": { $in: employeeNameArray }
},
{
$set: { "value_index": 500 }
}
)

但如我所说，需求要求更新的目标值是个性化的，不同的目标值之间是没有规律的。

那可否循环访问 MongoDB 一条一条地更新数据呢？否否否否否！虽然它的确能够实现需求，但是这个操作会严重影响数据库性能，在任何数据库中都要避免循环访问数据库。

1
2
3
4
5


for (let i = 0; i < data.length; i++) {
Employee.findOneAndUpdate(
{ "name": data[i].name },
{ "value_index": data[i].value_index }
)};

主角登场，bulkWrite()是 MongoDB v3.2中加入的新功能，能以特定的顺序执行 MongoDB 的写入操作，而这里的..写入操作..包括 insert、update、replace 等。使用方法：

1
2
3
4
5
6
7


Model.bulkWrite(
[ < operation 1 > , < operation 2 > , ...],
{
writeConcern: < document > ,
ordered: < boolean >
}
)

参数一是一个数组，表示一组数据库写操作，支持以下6个操作：

insertOne()

1
2
3


Model.bulkWrite([
{ insertOne: { "document": { "name": "Zander", ... } }
])

updateOne()和updateMany()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Model.bulkWrite([
{ updateOne: {
"filter": { "name": "Zander" }, // 查询条件，与 find()方法相同
 "update": { "value_index": 100 }, // 要执行的更新操作，可以是文档，也可以是聚合管道（如$set）
 "upsert": false, // 可选，Boolean类型，表示如果没有查询到该文档是否执行新增操作，默认为false
 "arrayFilters": [ { ... }, ... ], // 可选，更新文档中的嵌套数组
 "collation": { ... }, // 可选，指定更新操作的排序规则
 "hint": { ... } // 可选，指定要更新文档的索引
 } }
])

deleteOne()和deleteMany()

1
2
3
4
5
6


Model.bulkWrite([
{ deleteOne: {
"filter": { "name": "Zander" },
"collation": { ... }
} }
])

replaceOne()

1
2
3
4
5
6
7
8
9


Model.bulkWrite([
{ replaceOne: {
"filter": { "name": "Zander" },
"replacement": { "name": "Handsome", "value_index": 100, ... }, // 替换文档
 "upsert": false,
"collation": { ... },
"hint": { ... }
} }
])

参数二是一个对象，其中包含两个设置项，writeConcern和ordered，writeConcern写入关注用以设置 MongoDB 写入操作关注程度的高低，采用默认即可。ordered用来指定是否按照顺序执行参数一中的写入操作，默认为true ，若设置为无序，MongoDB 会对操作进行重排序以提高性能，具体应取决于你的写入操作是否是有序的。

使用bulkWrite()完成上面的需求：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


let operations = [];
for (let i = 0; i < data.length; i++) {
let updateObj = {
'updateOne': {
'filter': { '_id': data[i].name },
'update': { 'value_index': data[i].value_index }
}
};
operations.push(updateObj);
}
let result;
try {
result = await Employee.bulkWrite(operations);
} catch (err) {
return err.message || '更新出错';
}
return result;

bulkWrite()操作的返回值包括：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
"ok": 1, // 此次操作时候成功
 "writeErrors": [], //操作的错误异常
 "writeConcernErrors": [], // 写入关注错误
 "insertedIds": [], // 插入数据的id
 "nInserted": 0, // 直接插入操作计数
 "nUpserted": 0, // 更新插入操作计数
 "nMatched": 8, // 查询操作计数
 "nModified": 5, // 修改操作计数
 "nRemoved": 0, // 删除操作计数
 "upserted": [] // 更新插入操作的id
}

insert()和upsert()操作的区别在于前者不需要进行查询操作，直接将数据插入集合中，而后者会根据条件先在集合中查找数据，找到了则更新，找不到再执行插入操作。

还有一点是bulkWrite()需要使用try..catch捕获错误，原因是在执行bulkWrite()过程中，如果遇到了 Write Concern 以外的错误（即不可控的错误），有序操作（ordered为true）将在发生错误后..停止..并返回这单个错误，无序条件（ordered为false）下则..跳过..遇到的错误..继续处理..操作队列中所有剩余的写操作，最后在 writeErrors 中返回每个错误。

GitLab API 授权认证及使用

xuezenghui6@gmail.com (Zander Hsueh) — Thu, 26 Dec 2019 10:15:00 +0800

前言

通常，GitLab 的操作都是通过 Web 界面或命令行来完成的，但 GitLab 也提供了简单而强大的开放 API 来自动执行 GitLab 相关操作，查看项目信息、提交 Issues、合并分支……统统都在 docs.gitlab.com，GitLab API 大多为 REST API，但也同样支持 GraphQL API，并且 v5 版本的 API 将全部基于 GraphQL API，as Facebook does.

授权认证

绝大多数的 GitLab API 都是需要身份验证的，这毋庸置疑，其它公司的内部数据不能随随便便就被获取到，即使是公司内部也会有各个 Group 或 Project 的权限设置。

再以使用 GitLab API 的目的出发——主要是为了在公司 Portal 网站中..显示.. GitLab 中的项目信息、成员信息、Issues 等，这就要求在用户登录 Portal 网站时获取其 GitLab 内具体权限，以显示其权限对应的 GitLab 数据。问题出来了：Portal 网站如何经过 GitLab 的同意来获取用户数据？

API 的使用无非 CRUD，按照 GitLab API 清晰完整的文档来就可以了，如何进行身份验证才是重头戏，GitLab API 的身份验证有四种方法：

1. OAuth2 tokens

OAuth2 即 OAuth 2.0版本，是一个关于授权的开放网络标准，也是目前应用最广泛的授权认证方式。它的运行流程是这样的：

简单来说就是在第三方应用（客户端 Client）需要资源服务器（Resource Server）的数据时，资源拥有者（Resource Owner）同意后..授权..给客户端，客户端向认证服务器（Authorization Server）申请令牌（Token），认证服务器确认后发放令牌，客户端就可以拿着令牌去获取资源服务器的数据了。

这些步骤中最重要的又在于客户端如何得到用户的授权（Authorization Grant）从而拿到令牌（Access Token），OAuth 2.0提供了四种授权方式，其中授权码模式（Authorization Code Grant）是最严密完整的，也是绝大多数网站作为资源服务器时采用的授权方式（包括 GitLab）。授权码模式流程图：

以 GitLab 的 OAuth2 验证方式解释一下此流程（开发者视角）：

第一步、创建应用

在 GitLab Web 界面的 Setting ➡️ Applications 中注册用于提供 OAuth 验证的应用。重定向 URI（Redirect URI）本应设为第三方应用（本例中即为公司 Portal 网站）的线上 URI，处于开发阶段时也可设为本地应用运行后的访问路径，如http://localhost:8080/login，此重定向 URI 的作用下文会详述。页面还会要求选择 Scopes，表示此应用的..授权范围..，应根据第三方应用的具体需求选择，我选 api，嘿嘿嘿，应用成功创建后会显示其具体信息，包括应用 Id Application Id、应用密钥Secret、回调 URLCallback url 和权限 Scopes。

GitLab 要求 Redirect URI 中不能包含一些特殊字符，如 #。在 Vue 中如果 vue-router 采用了 hash 模式，就与 Redirect URI 的格式要求冲突了，因此 vue-router 应改为采用 history 模式，详参 HTML5 History 模式。

第二步、请求授权码

点击 Portal 中「GitLab 授权」按钮时使用 location.href 跳转至授权页面：

https://gitlab.zander.com/oauth/authorize?client_id=4e1fe77ba1d43b151428d907574er866a48af8dbc8766ea839a84a88c6dace39&redirect_uri=http://localhost:8080/login&response_type=code&state=zander&scope=api

URI 中的参数包括：

参数	是否必须	含义
client_id	true	注册 GitLab 应用成功后的 Application Id
redirect_uri	true	注册应用时设置的重定向 URI
response_type	true	返回的类型，授权码模式即为`code`
state	false	用于确认请求和回调的状态，OAuth 建议以此来防止 CSRF 攻击³
scope	false	权限设置，范围不得超出创建应用时的配置，以空格分隔

第三步、用户授权

发送请求后网页会跳转到 GitLab 的授权页面，先要求用户登录 GitLab，然后询问用户是否同意授权🥺。用户点击同意后页面便会返回一个包含授权码 code 和参数 state（如果你传了它的话）的重定向 URI 并跳转至对应的网页，即网页的地址栏变成了这样：

http://localhost:8080/login?code=90792302acc2a0724d44c74f43d0fd77f005723c9ae5def965b02675f532949a&state=zander

第四步、获取令牌 Token

既然拿到了 code，嘿嘿嘿😎，只需要一个 Post 请求就能拿到可任意调用 GitLab API 大军的虎符🐯—— Access Token。要注意的是，获取 Token 的操作是需要在第三方应用的..后台..完成的，以保证数据的安全性。

POST https://gitlab.zander.com/oauth/token

参数包括：

参数	是否必须	含义
client_id	true	注册应用的 Application Id
client_secret	true	注册应用的 Secret
code	true	上面获取到的授权码，但是其有效期很短，一般为10min
grant_type	true	授权方式，`authorization_code`
redirect_uri	true	颁发令牌后的回调网址

GitLab 收到此请求后便会向参数中的redirect_uri网址发送一段 JSON 数据，虎符在此：

1
2
3
4
5
6
7


{
"access_token": "a7e514632722f45a9edfe4e8624ec3fcd826ebbcb830055f180efee4533a50dd",
"token_type": "bearer",
"refresh_token": "360c6864b42247fafeaac4715fc524f939ca4545f8400126705144d7e37b5042",
"scope": "api",
"created_at": 1577427939
}

2. Personal access tokens

GitLab Web 界面中进入 Seting ➡️ Access Tokens，输入名字和到期日期就可以生成对应的 Access Token，注意生成后需要保存好 Token，因为生成的这条 Token 不会再出现第二次，虽然你可以继续生成新的 Token😑。最简单的一种验证方式，但是此方式要求用户~~必须登入 GitLab Web 页面进特定操作~~，不可取，自己玩玩倒是很方便。

4. GitLab CI job token

在 GitLab 内置的持续集成工具 GitLab CI 的 Job 中使用，每个 Job 可配置一个 CI job token，使用方式类似用户名和密码。

使用

有了 Token，就有了使用 GitLab API 的🔑，但是不同 Token 的使用方式也不同：

AOuth 2.0获取的 Token 类型是 bearer-tokens，需要在 GitLab API 请求中加入 Key 为Authorization，Value 为 Bearer <Token>的 Header。
Personal access tokens 获取的是 Private-Token，需要加入 Key 为Private-Token、Value 为 Token 值的请求 Header。

所有的 GitLab API 前缀均为https://gitlab.example.com/api/v4/，使用方式与常见 API 无异，例：

1

GET https://gitlab.example.com/api/v4/prjects

此 API 可获取到用户在 GitLab 上所有的可见项目列表：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71


[
{
"id": 1548,
"description": "demo",
"name": "Hello",
"name_with_namespace": "Zander Xue / Hello",
"path": "hello",
"path_with_namespace": "zander/hello",
"created_at": "2019-12-26T06:01:59.746Z",
"default_branch": "master",
"tag_list": [],
"ssh_url_to_repo": "git@gitlab.example.com:zander/hello",
"http_url_to_repo": "https://gitlab.example.com/zander/hello.git",
"web_url": "https://gitlab.example.com/zander/hello",
"avatar_url": null,
"star_count": 999,
"forks_count": 888,
"last_activity_at": "2019-12-26T06:01:59.746Z",
"_links": {
"self": "http://gitlab.example.com/api/v4/projects/1548",
"issues": "http://gitlab.example.com/api/v4/projects/1548/issues",
"merge_requests": "http://gitlab.example.com/api/v4/projects/1548/merge_requests",
"repo_branches": "http://gitlab.example.com/api/v4/projects/1548/repository/branches",
"labels": "http://gitlab.example.com/api/v4/projects/1548/labels",
"events": "http://gitlab.example.com/api/v4/projects/1548/events",
"members": "http://gitlab.example.com/api/v4/projects/1548/members"
},
"archived": false,
"visibility": "internal",
"owner": {
"id": 268,
"name": "Zander Hsueh",
"username": "zander",
"state": "active",
"avatar_url": "null",
"web_url": "https://gitlab.example.com/zander"
},
"resolve_outdated_diff_discussions": false,
"container_registry_enabled": true,
"issues_enabled": true,
"merge_requests_enabled": true,
"wiki_enabled": true,
"jobs_enabled": true,
"snippets_enabled": true,
"shared_runners_enabled": true,
"lfs_enabled": true,
"creator_id": 268,
"namespace": {
"id": 666,
"name": "zander",
"path": "zander",
"kind": "user",
"full_path": "zander",
"parent_id": null
},
"import_status": "none",
"open_issues_count": 0,
"public_jobs": true,
"ci_config_path": null,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"request_access_enabled": false,
"only_allow_merge_if_all_discussions_are_resolved": false,
"printing_merge_request_link_enabled": true,
"permissions": {
"project_access": null,
"group_access": null
}
},
"..."
]

References & Resources

来源：https://tools.ietf.org/html/rfc6749#section-1.2 ↩︎
来源：https://tools.ietf.org/html/rfc6749#section-4.1 ↩︎
详见 https://tools.ietf.org/html/rfc6749#section-10.12 ↩︎

Vuelidate

xuezenghui6@gmail.com (Zander Hsueh) — Wed, 18 Dec 2019 20:30:00 +0800

前言

Vuelidate 是 Vue.js 2.0 的一款表单验证工具，首先要表明的是选择其来做表单验证并是因为其相比于其它 Vue 表单验证工具有多么优秀，而是因为项目用到了一款基于 Material Design 风格的 UI 框架 Vuetify，此 UI 框架 v1.5.x 版本推荐使用的表单验证方式就是 Vuelidate（说商业胡吹吧 Vuelidate 官网也没提你 Vuetify 啊，是这个原因导致 Vuetify v2.0.x 版本又推荐了 Vee-validate 么？哈哈哈哈😄）。

用法

安装

1

$ npm install vuelidate --save

导入

在main.js中引入并使用：

1
2


import Vuelidate from 'vuelidate';
Vue.use(Vuelidate);

基础使用

1. 在组件中引入验证规则

使用插件最方便之处就在于不用自己逐个去写正则表达式，Vuelidate 提供了很多常见的内置验证规则：

验证规则	参数	作用
required	无	非空数据验证
requiredIf	flag¹	当 flag 为`true`时验证非空
requiredUnless	flag	当 flag 为`false`时验证非空
minLength	length	最小长度验证，包含 length 值
maxLength	length	最大长度验证，包含 length 值
minValue	value	数字或日期最小值验证
maxValue	value	数字或日期最大值验证
between	minValue, maxVulue	数字或日期指定区间验证
alpha	无	仅接受字母和字符
alphaNum	无	仅接受字母和数字
numeric	无	仅接受数字（不包含负数）
integer	无	仅接受正负整数
decimal	无	仅接受正负十进制数
email	无	电子邮箱验证
ipAddress	无	IPv4地址验证
macAddress	分隔符，如`:`、`' '`	MAC地址验证
sameAs	flag	验证与给定变量是否相等
url	无	网址验证
or	多个验证规则	当通过给定的至少一个验证规则时通过
and	多个验证规则	当通过所有的验证规则时通过
not	验证规则	当不通过给定的验证规则时通过，常与 sameAs 合用
要使用这些内置的验证规则只需在组件中按需引入：

1
2
3


<script>
import { required, numeric } from "vuelidate/lib/validators";
</script>

2. 验证表单

Vuelidate 最便捷的验证方式是基于 Vue 的v-model数据来验证。也就是说，Vuelidate 和 Vue 采用的是相同的代码与页面交互方式——数据驱动视图，Vuelidate 通过监听双向绑定的数据来动态判断其是否通过验证规则，从而再将验证通过与否的不同结果反馈给用户。

第一步、在 validations 中挂载需要验证的表单 data 数据

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


export default {
name: 'HelloWorld',
validations: {
zander: { required, numeric }
},
data() {
return {
zander: ''
}
}
}

第二步、用 Vuelidate 的$model管理表单数据

$model相当于v-model的替代，是对原始 data 数据的引用，在其它地方使用该数据时无需改变什么，this.$v.data.$model的值与this.data完全相同。被$model管理的数据含有一个 Boolean 类型的标志$dirty来表示数据是否改变，很容易理解——如果数据改动了，那它就是肮脏的🤣，$dirty置为 true。每当被验证的数据改变时 Vuelidate 都会验证一次数据是否通过验证规则。

$model的$touch()方法可以将$dirty的值手动设为 true，怎么用呢？如果你不想把 Vue 中的v-model="data"改为 Vuelidate 的v-model="$v.data.$model"，那就可以为输入框添加 change 方法，在 change 方法中再调用$touch()方法，两种方式的处理结果是完全相同的。

1
2
3


<input type="text" v-model="$v.zander.$model">
or
<input type="text" v-model="zander" @change="$v.zander.$touch()">

如果觉得..每当用户输入一个字符..就验证一次太频繁，可以加上v-model的.lazy修饰符来使验证频率改为..每当用户输入完成..后验证。

第三步、添加验证不通过的反馈

验证规则不通过自然要有反馈动作来提示用户哪里出错了或应该输入什么内容，如果在普通 Vue 项目²中使用 Vuelidate，要显示验证不通过的错误信息需要自己手动添加反馈信息的容器和样式，根据验证结果控制容器的显示与隐藏即可：

1
2
3


<input type="text" v-model="$v.zander.$model">
<div v-if="!$v.zander.required">不能为空</div>
<div v-if="!$v.zander.numeric">请输入数字</div>

而至此，我方才明白为什么 Vuetify 推荐使用 Vuelidate 了：

项目中每类表单的验证反馈几乎都需要统一的样式、合理的过渡动画，而这些，Vuetify 都替你做了🥰。相对的，在 Vuetify 中设置 Vuelidate 反馈的方式也有所不同了，也更简单了，只需要在给输入框绑定一个错误信息的属性，然后使用计算属性动态地设置验证反馈的具体文字：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<v-text-field v-model="$v.zander.$model" :error-messages="zanderErrors"></v-text-field>
...
export default {
computed: {
zanderErrors() {
const errors = [];
if (!this.$v.zander.$dirty) return errors; // 验证通过则返回空数组
 !this.$v.zander.required && errors.push("不能为空"); // 短路语法，如果非空验证不通过则加入此反馈信息
 !this.$v.zander.numeric && errors.push("请输入数字"); // 短路语法，如果数字验证不通过则加入此反馈信息
 return errors;
}
}
}

进阶操作

上面三步已经基本完成了大多数简单表单验证，下面就再介绍几个我在使用过程中碰到的需要注意的点。

1. 验证对象的某个属性

就像上文中的第二个 GIF，我们给两个输入框绑定的是同一个对象的两个属性，想要给每个属性都添加不同的验证规则，只需要绑定时使用.语法访问对象的属性，挂载时使用嵌套的形式即可：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


<v-text-field v-model="$v.zanderObj.memo.$model" :error-messages="memoErrors"></v-text-field>
<v-text-field v-model="$v.zanderObj.amount.$model" :error-messages="amountErrors"></v-text-field>
...
export default {
validations: {
zanderObj: {
memo: { required },
amount: { required, numeric }
}
},
data: () => ({
zanderObj: {
memo: '',
amount: ''
}
})
}

2. 自定义验证规则

Vuelidate 内置验证规则固然好用，但往往并不能满足我们的实际需求，比如需要一个调整薪资数目的验证规则，需要验证正负整数及正负小数，这就需要我们去自定义验证规则，Vuelidate 提供了帮助我们自定义基于正则表达式验证规则的方法regex()。

首先需要引入 Vuelidate 的 helpers 对象，然后就可以使用helpers.regex()函数自定义符合我们要求的正则表达式规则，函数有两个参数，分别为该验证规则的描述和正则表达式。最后，像使用内置验证规则一样简单地使用自定义规则吧：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


import { helpers } from 'vuelidate/lib/validators';
const money = helpers.regex('plusOrMinusFloatNum', /^(\-|\+)?\d+(\.\d+)?$/);
export default {
...
validations: {
adjustSalary: { required, money }
},
computed: {
amountErrors() {
const errors = [];
if (!this.$v.adjustSalary.$dirty) return errors;
!this.$v.adjustSalary.money && errors.push("请输入正确的调整数目");
return errors;
}
}
}

3. 提交表单的验证

当然，表单验证的目的是让其提交正确格式的数据，这就需要在点击提交按钮时判断数据的正确性，如果不正确则不向后台发送请求等。$invalid是用于表示数据是否通过验证的 Boolean 类型状态值，其值为 true 时表示验证不通过，此次提交操作无效。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


<template>
<div>
<input type="text" v-model="$v.zander.$model">
<button @click="submit">提交</button>
<div v-if="!$v.zander.required">不能为空</div>
<div v-if="!$v.zander.numeric">请输入数字</div>
</div>
</template>
<script>
import { required, numeric } from "vuelidate/lib/validators";
export default {
name: "HelloWorld",
validations: {
zander: { required, numeric }
},
data() {
return {
zander: ""
};
},
methods: {
submit() {
this.$v.$touch();
if (this.$v.$invalid) {
confirm('无效提交');
}
...
}
}
};
</script>

还有一个常用的方法是$reset()，它的作用与$touch()正相反，将所有被验证数据的$dirty标志置为 false 状态，常用于重置表单操作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


...
<button @click="reset">重置</button>
<script>
export default {
...
methods: {
reset() {
this.data = '';
this.$v.$reset();
}
}
};
</script>

4. 数组类型的验证

是的，通过一段时间的实践运用，我觉得有必要也记录一下数组类型表单的验证。也就是在 Vue 中使用 v-for 渲染的表单，要验证数组中每一个对象的某个属性的 value，就需要用到一个新的指令 $each，意思显而易见——“每一项”，看实例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


<div v-for="(item, index) in $v.arr.$each.$iter" :key="index">
<div>{{ item.$model.name }}</div>
<input :error-messages="arrErrors" v-model.trim="item.age.$model" />
</div>
<script>
export default {
validations: {
arrCount: {
$each: {
age: { required, numeric }
}
}
},
data() {
return {
arr: [
{
name: "Zander",
age: ""
},
{
name: "Chris",
age: ""
}
]
}
},
computed: {
arrErrors() {
const errors = [];
for (let i = 0; i < this.arr.length; i++) { // 因为是数组，所以要循环判断每一项是否通过验证
 if (!this.$v.arr.$each[i].age.$dirty) return errors;
!this.$v.arr.$each[i].age.required && errors.push("不能为空");
!this.$v.arr.$each[i].age.numeric && errors.push("请输入数字");
}
return errors;
}
}
};
</script>

要用 Vuelidate 使用数据双向绑定的方式管理数组确实是有点繁琐了哈...所以，替代的便易办法是使用 change 事件监听输入框内容的变化，在变化的时候执行 touch() 方法让其对内容进行验证，在要验证的表单中添加 Vuelidate 的 @input 或 @blur 实现：

1
2
3
4


<div v-for="(item, index) in arr" :key="index">
<div>{{ item.name }}</div>
<input :error-messages="arrErrors" @input="$v.arr.$touch()" v-model.trim="item.age" />
</div>

但是在 Vuetify 中验证数组表单有一个..小瑕疵..，如果数组中只有一项不通过验证，那么错误反馈会应用到数组表单中的每个要验证的属性，比如上面例子中的两个 age 的 <input> 标签都会提示错误，而不是只提示不通过验证的这一项。

Vuelidate 的功能远远不止于此，这里就只列举一些常见的用法和范例了。话说回来，其实项目中整体使用下来觉得 Vuelidate 也没有多么糟糕，具体情境具体考虑嘛！但个人觉得相对而言 Vee-validate 更为轻量，且验证的写法也更为简洁（Star 也更多😌）。当然，自身技术允许的话，撸一个 Vue 表单验证工具针对性地用于具体的项目是最好不过了。

flag 可以是变量或函数，用于动态地改变是否采用此验证规则。 ↩︎
这里的「普通」指的是没有采用任何 UI 框架，使用原生 HTML 语言编写的 Vue 项目。 ↩︎

GraphQL

xuezenghui6@gmail.com (Zander Hsueh) — Thu, 28 Nov 2019 13:04:32 +0800

前言

**“一种用于API的查询语言。”**

🌚看到 GraphQL 官网的这句介绍大概人人都是一脸懵逼的，写过 API、用过数据库查询语言，还就没见过用于 API 的查询语言。大概是因为我们平常所见的大多都是 RESTful API，而大量 B/S 模式的应用程序也让我们只倾向于「客户端发送请求获取数据，服务端处理请求返回数据」、客户端与服务端交互的方式只能利用 HTTP 协议中 GET、POST、PUT、DELETE 等 HTTP 动词的传统认知。

而 GraphQL 正是要打破这种认知的技术。在 GraphQL 中，客户端可以..不多不少..地获得其想要的数据，因为 GraphQL 中控制返回数据的是客户端，而不是 RESTful API 中完全取决于服务端（前端出人头地的时候到了？🧐）。其次，前端与后端交互的方式也由 HTTP 动词转变为 GraphQL 提供的 Query 和 Mutation 等。

实例体验

开始之前先推荐一个开放 API——美国太空探索技术公司 SpaceX 提供的开源 REST API，应有尽有的数据，详细完整的文档，还支持一键导入 Postman😏。

1. 使用 express-generator 搭建项目

2. 安装使用 GraphQL 需要的依赖

1

$ npm install graphql express-graphql axios

此处安装 axios 是为了直接在后台发送请求获取数据，也可选择使用 Postman 中的 GraphQL 功能测试。

express-graphql 可将 Express 服务端中的 HTTP 请求使用 GraphQL 管理。

3. 管理 HTTP 请求

在app.js文件中设置路由，表示所有的客户端请求都由 GraphQL 的 requst handler 处理：

1
2
3
4
5
6
7
8


const graphqlHTTP = require('express-graphql');
const schema = require('./schema');
app.use('/graphql', graphqlHTTP({
schema,
graphiql: true
})
);

graphqlHTTP()用于处理 GraphQL 的查询请求，它接收一个 options 参数，其中 schema 是一个 GraphQL Schema 实例，graphiql 设置为 true 可以在浏览器中直接对 GraphQL 进行调试。

4. Schema

Schema 是 GraphQL 的类型系统，用于参数验证和返回数据格式的设定，共有8种类型。

新建schema.js文件，定义两个对象类型：LaunchType 和 RocketType：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


const { GraphQLObjectType, GraphQLInt, GraphQLString, GraphQLBoolean, GraphQLList, GraphQLSchema } = require('graphql');
const LaunchType = new GraphQLObjectType({
name: 'Launch',
description: '发射的相关数据💨',
fields: () => ({
flight_number: { type: GraphQLInt, description: '发射编号' },
mission_name: { type: GraphQLString, description: '任务代号' },
launch_date_local: { type: GraphQLString, description: '发射时间' },
launch_success: { type: GraphQLBoolean, description: '是否成功' },
rocket: { type: RocketType },
})
});
const RocketType = new GraphQLObjectType({
name: 'Rocket',
description: '火箭的相关数据🚀',
fields: () => ({
rocket_id: { type: GraphQLString },
rocket_name: { type: GraphQLString },
rocket_type: { type: GraphQLString }
})
});

5. 获取数据，定义查询入口

使用 axios 发送 HTTP 请求获取 SpaceX 官方 API 的数据，定义RootQuery作为所有查询的入口，处理并返回数据（此举实为模拟从数据库中获取数据）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


const axios = require('axios');
const RootQuery = new GraphQLObjectType({
name: 'RootQueryType',
fields: {
launches: {
type: new GraphQLList(LaunchType),
resolve(parent, args) {
return axios.get('https://api.spacexdata.com/v3/launches').then(res => res.data);
}
}
}
});
module.exports = new GraphQLSchema({
query: RootQuery
});

6. 使用 GraphiQL 测试

项目文件夹下npm start，浏览器中输入 http://localhost:5000/graphql （端口号可在/bin目录夹下www文件中自行指定）启动 GraphiQL。

查询所有的flight_number:

查询想要的更多数据：

7. 指定参数实现单条数据查询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// schema.js
const RootQuery = new GraphQLObjectType({
name: 'RootQueryType',
fields: {
...
launch: { // 新的查询
 type: LaunchType,
args: { // 添加参数
 flight_number: {
type: GraphQLInt
}
},
resolve(parent, args) {
return axios.get(`https://api.spacexdata.com/v3/launches/${args.flight_number}`).then(res => res.data);
}
}
}
});

GraphQL + NodeJS + MongoDB

上述实例只是验证了 GraphQL 中的强大查询可以通过 Query 轻松地实现，但还有两件事需要去做：①连接数据库使用自己的数据；②新增、更新、删除操作，下面通过一个综合实例来完成。

某些操作上方实例体验中已涉及到，此处不再赘述😑

设置项目

1. 搭建项目目录

使用 express-generator 搭建项目，添加/models目录定义 MongoDB 集合的模型，添加/graphql/schema.js目录来完成 GraphQL 相关操作，最终目录结构：

.
├─ app.js
├─ bin/
│ └─ www
├─ package.json
├─ node_modules
├─ public
├─ images
├─ javascripts
├─ stylesheets/
│ └─ style.css
├─ models/
│ ├─ author.js
│ └─ book.js
├─ graphql/
│ └─ schema.js
└─ views/
├─ error.pug
├─ index.pug
└─ layout.pug

2. 安装所需依赖项

1

$ npm i express-graphql graphql mongoose --save

连接数据库并定义集合的模型

1. 使用 Mongoose 连接 MongoDB

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// 文件位置：app.js

const mongoose = require('mongoose');
mongoose.set('useFindAndModify', false);
mongoose.connect('mongodb://127.0.0.1:27017/demo', {
useNewUrlParser: true
})
mongoose.connection.on('connected', function () {
console.log('连接成功');
})
mongoose.connection.on('error', function () {
console.log('出错');
})
mongoose.connection.on('disconnected', function () {
console.log('连接断开');
})

2. 定义 Mongoose 数据模型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 文件位置：models/author.js

const mongoose = require('mongoose');
const Schema = mongoose.Schema;
const authorSchema = new Schema({
"name": String,
"age": Number
});
module.exports = mongoose.model("Author", authorSchema, 'authors');

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 文件位置：models/book.js

const mongoose = require('mongoose');
const Schema = mongoose.Schema;
const bookSchema = new Schema({
"name": String,
"page": Number,
"authorId": { type: mongoose.Types.ObjectId }
});
module.exports = mongoose.model("Book", bookSchema, 'books');

定义类型，完成 GraphQL 接口

Express 中传统的 RESTful 接口使用express-router来管理路由，并在不同路由中完成相应的数据库操作，而要结合 GraphQL 就不能使用这种方式了，需要使用 GraphQL 中的方法管理所有的 HTTP 请求，然后在 GraphQL 的接口中完成相应的数据库操作。

1. 定义请求入口，使用 GraphQL 管理所有的 HTTP 请求

2. 定义对象类型和字段

此处的 Schema 才真正决定请求返回的是怎样的数据结构，与 Mongoose 的 Schema 完全不同，后者实际只是为了定义 Model 完成数据库操作，比如author集合中本没有books字段，而在 GraphQL 的对象类型中定义以后客户端就可以拿到定义的相应数据。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82


// 文件位置：graphql/schema.js

const graphql = require('graphql');
const Author = require('../models/author'); // 引入作者模型
const Book = require('../models/book'); // 引入书籍模型

const { // 定义GrapQL中Schema的类型
 GraphQLObjectType,
GraphQLString,
GraphQLID,
GraphQLInt,
GraphQLSchema,
GraphQLList,
GraphQLNonNull
} = graphql;
// 定义Book的Schema，决定了其可以返回的数据包括哪些
const BookType = new GraphQLObjectType({
name: 'Book',
description: "书籍信息",
fields: () => ({
id: {
type: GraphQLID,
name: "id"
},
// _id: {
 // type: GraphQLID,
 // name: "也是id吗？"
 // },
 name: {
type: GraphQLString,
name: "书名", // 此处的name用于在GraphiQL Query栏输入字段时显示
 description: "书名" // 此处的description用于在GraphiQL Docs中显示
 },
page: {
type: GraphQLInt,
name: '页数',
description: '页数'
},
author: {
type: AuthorType,
name: '书的作者',
description: '书的作者',
resolve(parent, args) {
return Author.findById(parent.authorId);
}
}
})
})
// 定义Author的Schema
const AuthorType = new GraphQLObjectType({
name: 'Author',
description: "作者信息",
fields: () => ({
id: {
type: GraphQLID
},
name: {
type: GraphQLString,
name: '作者名',
description: '作者名'
},
age: {
type: GraphQLInt,
name: '作者年龄',
description: '作者年龄'
},
books: {
type: new GraphQLList(BookType),
name: '著作',
description: '著作',
resolve(parent, args) {
return Book.find({
authorId: parent.id
});
}
}
})
})

字段的name属性和description属性可设置在 GraphiQL 的 Query 栏中输入字段时或在 Docs 中显示对应的说明
resove()方法才是掌控返回具体数据的关键，如果不设置则根据字段名对应，BookType的author字段和AuthorType的books字段都是通过resove()进行了数据的关联，常用参数：
- parent：上一级对象，如 author 字段resove()中的parent为 Book，parent.authorId即为 book 集合中的authorId字段
- args：请求的参数，通常在 Query 和 Mutation 操作中使用

3. 定义具体接口，完成数据库操作

GraphQL 中的 Mutation 操作用于对数据进行新增、更改和删除操作，用法与 Query 类似。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89


const RootQuery = new GraphQLObjectType({ // 相当于js中定义了一个对象，然后在对象中添加各种方法
 name: 'RootQueryType',
fields: {
books: {
type: new GraphQLList(BookType),
description: '获取所有的书籍信息', // 此处的description用于在GraphiQL Query中显示
 resolve() {
return Book.find({});
}
},
book: {
type: BookType,
description: '根据书名获取书籍信息',
args: { // 定义参数
 name: {
type: GraphQLString
}
},
resolve(parent, args) {
return Book.findOne({
name: args.name
});
}
},
author:{
type: AuthorType,
description: "根据作者id获取作者信息",
args: { id: { type: GraphQLID } },
resolve(parent, args) {
return Author.findById(args.id);
}
},
authors:{
type: new GraphQLList(AuthorType),
description: "获取所有作者信息",
resolve(parent, args) {
return Author.find({});
}
}
}
})
const Mutation = new GraphQLObjectType({
name: 'Mutation',
fields: {
addAuthor: {
type: AuthorType,
args: {
name: { type: new GraphQLNonNull(GraphQLString) }, //GraphQLNonNull作用与Mongoose Schema中的required类似，设置参数为必须值
 age: { type: new GraphQLNonNull(GraphQLInt) }
},
resolve(parent, args){
let author = new Author({
name: args.name,
age: args.age
})
return author.save();
}
},
updateAuthor: {
type: AuthorType,
args: {
name: { type: new GraphQLNonNull(GraphQLString) },
age: { type: new GraphQLNonNull(GraphQLInt) }
},
resolve(parent, args){
let updateObj = {
name: args.name,
age: args.age
}
return Author.findOneAndUpdate({ name: args.name }, updateObj);
}
},
deleteBook: {
type: BookType,
args: {
name: { type: GraphQLString }
},
resolve(parent, args){
return Book.deleteOne({ name: args.name });
}
}
}
})
module.exports = new GraphQLSchema({
query: RootQuery,
mutation: Mutation
});

执行请求

查询所有作者信息：
根据书籍名查找书籍信息：
新增作者：
更新作者信息：
删除作者：

DataLoader

不知你是否发现了惊奇的一点：Mongoose 定义的authorSchema中并没有书籍相关的字段，所有操作数据库的方法中也没有用到populate及aggregate关联数据，但是上方「查询所有作者信息」的接口authors返回了..书籍..的所有信息。

没错，这就是 GraphQL 优越所在——在 Type 中自由地定义返回的数据（AuthorType的books字段）。但是问题也随之来了，这类简单的..关联查询..实际会导致严重的 N + 1查询性能问题。

N + 1

一旦你学习完 GraphQL 的基础知识就大概率会看到大家在谈论 N + 1问题，N + 1是什么呢？为了理解起来更简单，我新建了 persons 和 friends 集合，其数据结构如下：

persons 数据：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
"_id" : ObjectId("5df49a5856652a298949e313"),
"name" : "Zander",
"age" : 18,
"alive" : true,
"friends" : [
ObjectId("5df49a7556652a298949e31d"),
ObjectId("5df49aa256652a298949e331")
]
}

friends 数据：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
"_id" : ObjectId("5df49a7556652a298949e31d"),
"name" : "Tom",
"tel" : "120",
"email" : "tom@gmail.com"
}
{
"_id" : ObjectId("5df49aa256652a298949e331"),
"name" : "Jerry",
"tel" : "110",
"email" : "jerry@gmail.com"
}

接下来是同样的步骤——新建 personType 和 friendType，再建立简单的 personQuery：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


const personQuery = new GraphQLObjectType({
name: 'personQueryType',
description: '查询人物信息',
fields: {
person: {
type: personType,
description: '获取人物及朋友信息',
args: {
name: {type: GraphQLString}
},
resolve: (parent, arg) => {
return Person.findOne({name: arg.name});
}
}
}
})

然后在 GraphiQL 中执行这个简单的 Query：

{
person(name: "Zander"){
id,
name,
age,
alive,
friends{
name,
tel,
email
}
}
}

按照 GraphQL 的机制会这样执行查询流程：

第一步：先查询 persons 集合中 name 为 Zander 的信息：

1
2
3


resolve: (parent, arg) => {
return Person.findOne({name: arg.name});
}

第二步：对于 Zander 的 friends 数据，GraphQL 会拿着friends数组中的 id 去匹配 friends 集合的_id字段，执行的查询大概是这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


resolve_1: (parent, arg) => {
return Friend.find({_id: parent.id_1});
}
resolve_2: (parent, arg) => {
return Friend.find({_id: parent.id_2});
}
...
resolve_n: (parent, arg) => {
return Friend.find({_id: parent.id_n});
}

如此，便产生了对数据库的 N + 1次请求。

我倒觉得叫1 + N 问题更合适🌚，因为总是先进行1次主集合数据查询，然后再去查询关联的 N 条数据。

Whatever! 先来解决问题吧～

解决问题

对于 N + 1问题，GraphQL 的开发者 Facebook 提供了 DataLoader 来作为通用的解决方案，为什么说是「通用」呢？因为几乎每种语言都有 DataLoader 的实现方式——JavaScript、Java、Python、PHP、Ruby......。DataLoader 通过批处理和缓存来减少 API 对数据库的访问次数。

批处理是 DataLoader 的主要功能，作用是如果需要多次访问数据库，则将这些功能类似的请求合并处理。

使用 DataLoader 的批处理函数需要满足两点：

批处理函数接受一个数组参数，返回的查询结果数组长度与参数数组长度相同且索引对应
返回的数组必须为 Promise 对象

1. 安装 DataLoader

1

$ npm install dataloader --save

2. 引入 Dataloader，定义 Dataloader 对象，将其挂载到所有请求的上下文中

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


const DataLoader = require('dataloader');
app.use('/graphql', graphqlHTTP(req => {
const friendLoader = new DataLoader(
keys => Friend.find({_id: {$in: keys}})
)
const loaders = {
friend: friendLoader
}
return {
context: {loaders},
schema,
graphiql: true
}
}));

网上很多案例都对返回的查询结果做了Promise.all()处理，但是在 Mongoose 中，所有的数据库操作返回的结果都是一个 Mongoose Documents，本身就是一个 Promise 对象，因此不用做相应的处理。

3. 修改获取 friends 数据的方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


const personType = new GraphQLObjectType({
name: 'person',
description: "人物信息",
fields: () => ({
id: {
type: GraphQLID
},
name: {
type: GraphQLString,
name: "姓名",
description: "姓名"
},
age: {
type: GraphQLInt,
name: '年龄',
description: '年龄'
},
alive: {
type: GraphQLBoolean,
name: '是否活着',
description: '是否活着'
},
friends: {
type: new GraphQLList(friendType),
name: '朋友',
description: '朋友们的信息',
resolve: (parent, args, {loaders}) => {
// return Friend.find({_id: {$in: parent.friends}}); // 不使用Dataloader
 return loaders.friend.loadMany(parent.friends);
}
}
})
})

你以为这就完了吗？是的没错🤪然而就这点简单的代码竟花费了我数天的时间，原因是网上竟没有找到完完全全的 Express + Mongoose + MongoDB + GraphQL + DataLoader 实例，完成这个实例确是摸石头过河，报了很多错、踩了很多坑才终取得真经。

然而如何去验证成功使用 DataLoader 解决了 N + 1是个问题，也就是目前还不知道如何监控 MongoDB ..集合..的查询次数、时间等信息，使用 mongostat、mongotop 等监控方法都没能达成此目的。

Apollo

Apollo GraphQL 是一个用于创建 GraphQL 客户端和服务器的完整独立系统，其完整性和独立性体现在不管你服务端使用的是 Java、Node.js、Python 或其它语言，也不管你客户端运用的是 React，React Native，Vue 还是 Angular，它不依赖于特定语言和框架，能很好地满足你对 GraphQL 的实现，并且是一套成熟完整的生态系统。

服务端实现——Apollo Server

Apollo Server 可以与流行的几个 Node.js 框架集成，包括 Express、Fastify、Koa 和 Hapi，下面介绍如何在 Express 中搭建 Apollo Server。

1. 设置项目

还是使用 express-generator 搭建项目目录，使用 Mongoose 连接 MongoDB，接下来安装依赖项：

1

$ npm i apollo-server-express graphql

2. 初始化 Apollo Server

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


const { ApolloServer } = require('apollo-server-express');
const typeDefs = require('./schema/schema'); // GraphQL的Schema
const resolvers = require('./schema/resolvers'); // API方法

const server = new ApolloServer({
typeDefs,
resolvers,
playground: { // 配置playground
 settings: {
'editor.theme': 'light'
}
}
});
server.applyMiddleware({ app }); // 应用中间件，传递数据到express的app，必须位于`const app = express();`下方

app.listen({ port: 4000 }, () =>
console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`)
)

3. 添加 Schema

Apollo Server 中内置了 gql 模板字符串，新建 schema/schema.js 目录，定义 GraphQL 的 Schema（类型系统）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


const { gql } = require('apollo-server-express');
const typeDefs = gql`
 type Person {
 id: String
 name: String
 age: Int
 alive: Boolean
 }
 type Friend {
 id: String
 name: String
 tel: String
 email: String
 }
 type Query {
 allPerson: [Person]
 person(name: String!): Person
 }
`;
module.exports = typeDefs;

4. 添加返回数据的方法

resolvers 用于定义 GraphQL 操作（Query、Mutation、Subscriptoin）返回的具体数据，在 /src/schema/resolvers.js 中添加：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


const Person = require('../models/person');
const resolvers = {
Query: {
allPerson: () => {
return Person.find();
},
person: (parent, args) => {
return Person.findOne({name: args.name});
}
}
};
module.exports = resolvers;

5. 在 playground 中测试 GraphQL API

客户端实现——Vue Apollo

Vue Apollo 通过声明式查询将 Apollo 集成到 Vue 组件中，是 Vue 中使用 GraphQL 的官方实现方法。

1. 安装

Vue CLI 3 中安装 Apollo 十分简单，直接添加插件即可：

1

$ vue add apollo

建议可选项：

? Add example code? No
? Add a GraphQL API Server? No
? Configure Apollo Engine? No

当然你要是头铁（依赖项实在太多）也可以选择手动安装。

2. 配置 vue-apollo

生成目录中的 vue-apollo.js 是 apollo 的配置文件，需要做的有两点：

由于服务端中没有设置 WebSocket 端点，需要将配置文件中的 wsEndpoint 设置为null。
设置 http 端点 httpEndpoint 为 Apollo 服务端中所设置的 GraphQL 请求入口 URL，由于我服务端并没有特殊配置入口 URL，此处无需改动。

3. 在 Vue 组件中使用 GraphQL 查询语句

在组件中使用 GraphQL 查询有三种方式，而使用 GraphQL API 返回的数据就和使用 data 中的数据一样简单：

**方式一、**在组件中引入 gql 模板字符串语法，然后在组件中声明 apollo 查询来定义查询语句：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


<template>
<div>
<div v-for="person in allPerson" :key="person.id">
name: {{ person.name }},
age: {{ person.age }},
alive: {{ person.alive === true? "是":"否" }}
</div>
</div>
</template>
<script>
import gql from "graphql-tag";
export default {
name: "HelloWorld",
apollo: {
allPerson: gql`
 query {
 allPerson {
 id
 name
 age
 }
 }
 `
}
};
</script>

**方式二、**为了查询语句的可重用性和可维护性，建议采用引用公共 gql 语句的方式。新建 /src/graphql/ 目录，在目录下新建.gql文件来定义项目所需的 GraphQL 操作，然后在组件中引入并使用：

1
2
3
4
5
6
7
8
9


// 文件位置：/src/graphql/allPerson.gql
query allPerson{
allPerson{
id,
name,
age,
alive
}
}

在组件中使用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<script>
import allPerson from '../graphql/allPerson.gql'
export default {
name: "HelloWorld",
apollo: {
allPerson: allPerson
}
};
</script>

**方式三、**使用 Apollo 组件也是一种办法，这种方式的优点在于可以脱离 Vue 组件的<script>标签，适用于在 Vue ..公共组件..中使用，但也太不优雅了🙃：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


<template>
<div class="hello">
<ApolloQuery
:query="gql => gql`
 query {
 allPerson {
 id
 name
 }
 }`"
>
<template v-slot="{ result: { loading, error, data } }">
<div v-if="data">
<div v-for="person in data.allPerson" :key="person.id">
name: {{ person.name }},
age: {{ person.age }},
alive: {{ person.alive === true? "是":"否" }}
</div>
</div>
</template>
</ApolloQuery>
</div>
</template>

当然，这三种方式带来的结果是相同的：

References & Resources

GraphQL & DataLoader：

Apollo：

JavaScript 此间道理汝明了之？

xuezenghui6@gmail.com (Zander Hsueh) — Wed, 27 Nov 2019 13:04:32 +0800

前言

了解了语法拿来就用？搜到了例子照搬不误？NoNoNo！作为21世纪的前端新势力应该树立“书写合格且优雅的规范代码”之最佳典范，高举“大前端是未来趋势”之伟大旗帜，秉持“JavaScript 是世界上最好的语言”之行业思想……以下关于 JavaScript 中各语法在各业务情境中的使用都是博主一坑一坑踩过来的🥺，一为..记录..，二为..分享..，愿我们下（qiāo）笔（xià）写（jiàn）出（pán）的都是极具可读性、可扩展性和良好健壮性的高质量代码。

🍽食用方法：正文中的三级标题为用法的简要，..🤔..后是该用法的原理及相关思考，..🔗..为推荐阅读的相关链接。

干货

创建空对象的正确方式—`Object.create(null)`

🤔：JavaScript 编程中的最佳实践，Object.create(null)创建的对象不会继承 Object 原型的toString()、hasOwnProperty()等方法，真正的..空对象..，干净而优雅🤤～而使用{}则反之。
🔗：
1. 详解 Object.create(null) | 掘金

慎用`delete`来删除对象的属性

🤔️：JavaScript V8 引擎内部机制导致delete操作会先耗费大量时间去检查对象中的各个属性，从而大大影响程序的执行速度。简单的方式是直接将不需要的属性设为undefined，但这种方式实际只保证了属性不显示，而不是真正意义上的..删除..（会导致 ESlint 报错），Lodash 的 pick() 或 omit() 方法实为最优解。
🔗：
1. Slow delete of object properties in JS in V8 | Stack Overflow
2. 为什么说在 JS 中要避免使用 delete | SegmentFault

最优雅地实现数组去重并排序

1

arr = [...new Set(arr)].sort((a, b) => a - b);

🤔：ES6 中的Set数据结构类似于数组，其内所有元素的值都是唯一的，不含重复值，扩展运算符...将 Set 实例转为了数组，然后再用数组排序方法sort()进行从小到大的排序。
🔗：
1. Set 和 Map 数据结构 | ECMAScript 6 入门 - 阮一峰
2. 数组的扩展 | ECMAScript 6 入门 - 阮一峰

利用短路语法替代简单的条件语句

1
2
3
4
5


if (zander === 'developer') {
console.log('He is cool!');
}
// ⬇️
zander === 'developer' && console.log('He is cool!');

1

const length = (zander || []).length;

🧐：&&运算保证第一个参数为 true 时才会执行后面的代码，||运算保证第一个参数为 false 时才会执行后面的代码。短路运算的效率略高于if条件语句，但只适用于简单的if..do...语句优化，如参数验证、设置默认值等。
🔗：
1. 逻辑运算符 | MDN

高效地格式化数字

1
2
3


const toDecimalMark = num => num.toLocaleString('en-US');
toDecimalMark(19971122.05); // '19,971,122.05'

🧐：这是一个格式化数字函数，可将数字高效地转换为逗号分隔的数字..字符串..，而不用写一堆正则去处理。toLocaleString() 是 ECMAScript 中的标准方法，用于返回特定语言环境下格式化后的字符串。
🔗：
1. Number.prototype.toLocaleString() | MDN

根据对象的 Value 获取对应的 Key

1
2
3


function getKey(obj, value, compare = (a, b) => a === b) {
return Object.keys(obj).find(element => compare(obj[element], value));
}

🧐：要通过 Value 找到 Key 是离不开遍历的，先使用 Object.keys() 方法返回对象可枚举属性组成的数组，数组的 find() 方法可在遍历时完成键值的匹配。但这只针对无相同 Value 的对象，否则只会返回匹配到的第一个 Key，如果没有匹配到的 Key 则返回 undefined。
🔗：
1. Object.keys() | MDN
2. Array.prototype.find() | MDN

最平滑之滚动

1
2
3
4
5
6
7


const scrollToTop = () => {
const c = document.documentElement.scrollTop || document.body.scrollTop;
if (c > 0) {
window.requestAnimationFrame(scrollToTop);
window.scrollTo(0, c - c / 8);
}
}

🧐：scrollTop 获取了当前滚动条距离顶部的垂直距离，如果这个距离大于 0，调用神奇的 requestAnimationFrame API，它传入一个回调函数，让..浏览器..根据其重绘周期和屏幕帧数来执行回调、一帧一帧地更新动画，使动画更平滑，而这里的动画就是 scrollTo——滚动事件。（注：使用此方法需考虑兼容性问题）
🔗：

Bit

xuezenghui6@gmail.com (Zander Hsueh) — Tue, 19 Nov 2019 20:18:00 +0800

前言

现在几乎每个前端都可以在嘴边挂着组件化、模块化，但是真正做到组件化、模块化开发的项目..寥寥无几..。比如我们接触的每个 Vue 项目中几乎都有 components 目录，但是其中的 Vue 组件都和这个项目有着不可切割的关系，如果某天要把这个所谓的..公共组件..用于其它项目上，就会发现——压根儿拔不动、抽不出。

究其根本，造成这个不理想的结果原因很多。代码层面上，不同项目中的 UI 设计风格不同、组件中包含特定项目的依赖（如各种 UI 框架）、组件之间存在复杂的相互依赖关系，都导致组件难以抽离；人为层面上，开发人员在组件化开发概念上不够深入、组件的拆分上做的并不合理，也让组件化的发展停滞不前，而更重要的一个原因在于没有一个合适的用来管理组件的工具，组件化很关键的一个因素在于组件的管理，包括组件的发布、修改、详细使用文档、demo 展示等，而现有的代码管理工具如 Git、NPM 却很难在..组件..的层面上有效管理代码。

Bit 来了

Bit 是一个强大的组件协作平台，它能跨项目、跨存储库地隔离并管理组件，可在众多框架及工具中使用，如 React、Vue、Angular、Node.js、Mocha、Jest 等。

“ Bit loves Git ”—— yep，这是 Bit 官方文档的原话。Git 大家再熟悉不过了，世界上最先进的 DVCS¹，「近朱者赤」，大概这就是 Bit 喜欢 Git 的原因了吧 hhhh～😆

Just joking ，其实是因为 Bit 的工作流和 Git ..很相似..，我们通常用 Git 来管理源文件、源代码，而 Bit 也是用来管理代码的，但不同的是 Git 不管你代码的语义结构，一股脑儿来进行管理。而 Bit 则是将代码..分组件..管理的，换句话说—— Bit 用来管理组件。

Bit 的工作流和 Git 怎么个类似法呢？

首先，安装 Bit 后可以将本地的代码分组件发布到 Bit Server 中的 Collection 中，类比 Git 将本地仓库代码推送到远程仓库。
在远程的 Bit Server 中可以预览、管理发布的组件，类比在 GitHub、GitLab 等代码管理工具上查看、管理远程仓库中的文件。
可以在别的代码区安装并引入发布的组件，可跨机器使用、跨项目使用，甚至跨语言使用已发布的组件，这点和 NPM 的方式倒很类似，继续往下看你会发现 Bit 和 NPM 确是有着千丝万缕的关系。

安装

使用 NPM/Yarn 安装：

1
2


$ npm install bit-bin -g
$ yarn global add bit-bin

MacOS 也可使用 Homebrew 安装：

1

$ brew install bit

使用 Bit 管理 Vue 组件

组件，简单点说就是可重复使用的代码段，包含但不限于：

React、Vue、Angular 组件
公共样式文件，如 CSS、SCSS 文件
重复使用的函数、方法

当 Bit 存储一个组件时会存储这段代码的三个元素：

1. 源代码

源代码是组件内容的根本，Bit 将源代码映射到组件并指定一个 main 文件作为组件的入口。

2. 依赖关系图

这是 Bit 的一个强大特性，当源代码保存为 Bit 组件时，Bit 会分析其中包含的所有依赖项（即代码中的 import 和 require 语句），然后创建一个组件的依赖关系图，这样，即使组件被抽离，它也是独立的，因为所有的依赖项都会被记录追踪。

**两点说明**

1⃣️ Bit 可追踪的依赖项只包含使用 NPM 安装的依赖和安装/使用的 Bit 组件，就是说项目中直接通过绝对/相对路径引入的本地组件..不被包含..在依赖项内，如 import Utils from './utils.js'，那如果组件在另一个项目中使用不就找不到引入的文件了吗🤔️？当然，Bit 从根本上避免了这种情况的产生——需要将引入的本地组件与主组件同步追踪才可发布👍。

2⃣️ 如果要发布的组件中使用了第三方 UI 框架（如 Vuetify 中特有的标签 v-card 等），Bit 并不会自动分析出它依赖了这个 UI 框架，而是可以直接发布，但在使用此组件的项目中需要安装对应的 UI 框架才能正确显示 Bit 组件。

3. 工具与配置

Bit 还会将组件特有的工具和配置保存下来，比如组件使用的编译器和测试工具等。

发布组件

1. 初始化项目

1

$ bit init

当运行 init 命令时，Bit 会在项目中创建三个资源：

bit config：位于 (package.json ? package.json : bit.json) 中，Bit 工作区配置文件，包括导入组件默认保存的文件夹、包管理工具等配置项。
.bit 目录：Bit 的工作区，之后创建和导入的组件信息都位于此目录中。
.bitmap：Bit 组件图，描述了组件和组成组件的文件之间的链接关系。

导入指使用 bit import 命令将远程的组件添加到工作区，而使用 NPM/Yarn 安装的 Bit 组件只是常规的包，两者有着很大的区别，详询 Imported Components。

2. 跟踪组件

跟踪操作将本地项目中的一个或多个文件转换为了 Bit 组件，然后会保存上面提到的三个元素。如：$ bit add src/components/HelloWorld.vue --id my-hello

1

$ bit add <file_path> --id <component_id>

如果一个文件内通过 require 或 import 引入了另一个文件，只需将它们一同跟踪，Bit 会自动分析他们之间的依赖关系：

1

$ bit add src/components/father.vue src/components/son.vue --id father-son

也可直接跟踪一个目录下的所有组件：

1

$ bit add src/components/* --namespace hello

添加 --namespace hello 选项意为使用 hello 作为 src/components/ 目录下所有跟踪组件的父级目录，即生成的组件名为 hello/filename1、hello/filename2。

3. 设置组件版本

1

$ bit tag --<component_id> <version>

执行此操作后 Bit 会锁定该组件的依赖项版本，运行编译并测试该组件（可使用 --verbose 选项查看组件测试结果），如果编译测试通过则会设置组件的版本并自动标记依赖于该组件的组件。如：$ bit tag --my-hello 1.0.0

使用 $ bit untag <component_id> <version> 命令可取消设置的版本号。

4. 导出组件

导出组件即把组件上传到远程仓库中，远程仓库分两种，一种是 Bit 提供的组件中心 bit.dev，在组件中心中可以预览、托管、组织发布的组件，功能强大；还有一种是自己搭建的 Bit Server，下文会详细讲述。先来看如何导出到可以白嫖的 bit.dev 中：

在 bit.dev 中申请账号
创建一个公共的或私有的集合，用以存储组件
在项目中使用 $ bit login 登录，Bit 会自动打开浏览器进行身份验证😎

发布组件：

1

$ bit export <user_name>.<collection_name>

查看、管理组件

始言之，「组件化一个很关键的因素在于组件的管理」，Bit 在这点上的优势就在于——bit.dev，在平台上可以浏览、使用所有公开的组件，有点像 Codepen。也可以管理自己已发布的组件，包括编辑组件文档，查看各个版本组件的代码、参数、依赖关系、安装命令等等，还可以在 Playground 中实时编辑、预览组件效果（这点太棒了，但是中文在缩略图上显示异常😡）：

但是，可惜的是 bit.dev 的目标是成为用来托管组件的 SaaS³，也就是说它是用来赚钱的。普通用户只可创建三个私有集合，要想一刀999级就要付费了，而且价格还不低——$200/month……

安装并使用组件

1. 安装组件

如果将组件发布至 bit.dev，那么使用 NPM 或者 Yarn 是在其它项目中最方便快捷安装使用 Bit 组件的方式，安装组件的命令位于 bit.dev 中组件页面的右上角。

第一步需要在 NPM 注册表中配置 @bit：

1

$ npm config set @bit:registry https://node.bit.dev

然后就可以像 NPM/Yarn 安装第三方包一样安装 Bit 组件了：

1
2


$ npm i @bit/zander.hello.my-hello
$ yarn add @bit/zander.hello.my-hello

使用也是同样简单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


<template>
<v-app>
<top-bar />
<v-content text-center>
<v-row class="text-center mt-10">
<v-col cols="12">
<my-hello msg="使用组件😉" />
<father-test />
<vuetify />
</v-col>
</v-row>
</v-content>
</v-app>
</template>
<script>
import TopBar from "@bit/zander.hello.top-bar";
import MyHello from "@bit/zander.hello.my-hello";
import FatherSon from "@bit/zander.hello.father-son";
import Vuetify from "@bit/zander.hello.vuetify";
export default {
name: "App",
components: {
TopBar,
MyHello,
FatherSon,
Vuetify
}
};
</script>

2. 导入组件

导入组件指将远程组件的所有信息下载到本地，包括组件的源代码、依赖项等，导入的文件位于配置文件 package.json 中 componentsDefaultDirectory 项定义的目录中。

在其它项目中要想使用发布在 Bit Server 中的组件只能..导入组件..，而不能使用 NPM or Yarn 的方式。如果是在新项目中第一次..导入.. Bit 组件需先运行 $ bit init 命令。

1

$ bit import <user_name>.<collection_name>/<component_id>

可加入组件固定版本，如 $ bit import zander.hello/my-hello@1.0.1，不加则默认导入最新版本。

同样的，使用组件的方式还是引入再使用，不过不能直接引入组件的路径，引入组件的全名即可（package.json 中的名字）：

1

import myHello from "@bit/zander.hello.my-hello";

更新组件

更新组件有两个角度，一种是远程的组件更新了，使用该组件的项目需要同步更新；另一种是在使用组件的项目中需要对导入的组件进行更改并上传至远程。

1. 更新本地组件

本地的组件要想同步远程的更新直接使用导入命令即可，组件的最新版本会被自动导入：

1

$ bit import <component_id>

2. 修改组件并更新至远程

项目中如果修改了通过 $ bit import 导入的组件就需要将组件更新至远程，这样其它使用者才可同步此修改。

当修改组件后运行 $ bit status 命令会提示 modified components 的相关信息，此时可为组件设置新的版本：

1

$ bit tag <component_id> <new_version>

然后将其重新导出到远程集合中：

1

$ bit export <user_name>.<collection_name>

弃用或删除组件

当不使用一个组件的时候有两种选择：

1. 弃用组件

弃用组件意味着 Bit 会将其标记为“已过时”，但不会影响组件正常使用。

1

$ bit bit deprecate <user_name>.<collection>/<component_id> --remote

2. 删除组件

删除一个组件需要考虑是否有其它组件依赖此组件，所以一定要慎重操作。

1

$ bit remove <user_name>.<collection>/<component_id> --remote

Bit Server

Bit Server 就是 bit.dev 的代替工具了，且是超低配版，它能提供的功能只有作为“远程仓库”来..存储..组件，本地通过 SSH 来与 Bit Server 通信，发布和导入组件就相当于 Bit Server 的存和取操作了。相对的，功能不健全但成本也相对较低，要使用 Bit Server 只需要一个服务器就够了。

常用命令

Command	Function	Options
`bit init`	初始化 Bit 环境	`--package-manager`：设置包管理工具
`bit login`	登录到远程
`bit logout`	注销已登录账号
`bit list`	显示远程和本地所有组件
`bit status`	查看工作区中被跟踪组件的状态
`bit add <file_path> --id <component_id>`	追踪组件	`--id`：指定组件 ID `--namespace`：设置命名空间 `--exclude`：排除文件
`bit untrack <component_id>`	取消追踪组件
`bit show <component_id>`	查看组件的依赖关系
`bit diff <component_id>`	比较更改前后组件的变化
`bit log <component_id>`	查看组件各版本信息
`bit tag <component_id> <version>`	设置组件版本号	`--message`：版本描述 `--all`：为所有新增和修改的组件设置
`bit untag <component_id> <version>`	取消设置的版本号	`--all`：取消设置的所有组件的版本号
`bit export <user_name>.<collection_name>`	导出到远程	`--eject`：导出后将本地代码替换成该组件 `--all`：导出所有
`bit import <user_name>.<collection_name>/<component_id>`	导入组件
`bit deprecate <component_id>`	弃用组件	`--remote`：同时从远程弃用
`bit remove <component_id>`	删除组件	`--remote`：同时从远程删除

总结

首先，Bit 的确是为前端组件化、代码片段管理提供了一套不错的解决方案，如果组件都能..跨项目..地去使用，而且只需要一行 Bit 命令就可以解决，既保证了开发的高效性，也能保证组件的整体质量及可复用性。

如果前端的工作方式都切换到 Bit 模式上，那么从发布方式、规范化、标准化等方面来说就没得挑，因为你发布的组件别人要用得上、可以用、用得爽啊！所以，从这里来看 Bit 的确可以规范前端组件标准，有效解耦前端代码。

但是，以 Bit 目前的知名度和普及度来看，它还有很长的路要走，这也不是没有原因的：

bit.dev 不开源，自行搭建的 Bit Server 功能实在是太有限了，这点真的是太失望了🙍‍♂️……
Bit 没有像 GitHub、GitLab 这样的可以以项目为单位管理组织代码的机制，以至于看起来像是 Codepen 这样的交流社区。
权限管理功能欠缺。

分布式版本控制系统，Distributed Version Control Systems。 ↩︎
图源：https://docs.bit.dev/docs/quick-start ↩︎
Software-as-a-Service，软件即服务，一种软件应用模式。 ↩︎

MongoDB 中的关联查询

xuezenghui6@gmail.com (Zander Hsueh) — Thu, 14 Nov 2019 13:25:10 +0800

前言

数据库设计中数据之间的关联关系是极其常见的：一对一、一对多、多对多，作为 NoSQL 领头羊的 MongoDB 中常用做法无非「内嵌」和「引用」两种，因为 Document 有 16MB 的大小限制¹且「内嵌」不适合复杂的多对多关系，「引用」是用得更广泛的关联方式，所以 MongoDB 官方称其为“Normalized Data Models”——..标准化数据模型..。

² 引用式的关联其实很简单，指文档与文档之间通过_id字段的引用来进行关联。在需要 user 集合中“123xyz”的所有信息时只需要再..多查..两个表就可以得到。而本文要阐述的重点就在于如何去多查这两个表——aggregate 与 populate。

剖析

aggregate

先来说说 aggregate 吧，为什么要先说它呢？因为人家是 MongoDB 提供的功能——正儿八经血统纯正官方推荐啊🌚，而且不得不提的是 aggregate 也是我刚开始接触 Node.js + MongoDB 就误打误撞使用到的..业务核心技术..，使用其编写了不少现在正在和公司大佬一起重构的接口🤪……这个问题下文会讲到。

aggregate 聚合其实是 MongoDB 提供的比较大的功能模块了，而关联多个集合需要用到的是$lookup，比如有作者集合 authors 和著作集合 books，作者与著作即为「一对多」的关联关系，使用引用式关联：

因为技术栈是 Node.js + Express + Mongoose，以下代码示例也以此为基础，使用 express-generator 生成 demo 目录结构。

使用 aggregate 实现聚合查询作者 Zander 的基本信息及其所有著作信息：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


router.get('/getAuthorInfo_a', async (req, res) => {
let result = await Author.aggregate([{ // 操作的Model为Author
 $lookup: {
from: "books", // 数据库中关联的集合名
 localField: "books", // author文档中关联的字段
 foreignField: "_id", // book文档中关联的字段
 as: "bookList" // 返回数据的字段名
 }
}, {
$match: { // 筛选条件
 "author": "Zander"
}
}]);
res.json({
status: 200,
result: result
})
});

返回数据：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


{
"status": 200,
"result": [
{
"_id": "5dccfc3aa3fab06c89020c65",
"author": "Zander",
"age": 18,
"bookList": [
{
"_id": "5dccfcb5a3fab06c89020c8d",
"name": "代码的弱点"
},
{
"_id": "5dccfd30a3fab06c89020caa",
"name": "代码与六便士"
},
{
"_id": "5dccfda6a3fab06c89020cc3",
"name": "代码失格"
}
]
}
]
}

aggregate 使用方法并不难，抛开结果先不谈，来看看 populate 的实现方式。

populate

populate 是 Mongoose 中提供的方法，且 Mongoose单方言之populate()比 MongoDB 的$lookup更为强大🧐。那就拉出来溜溜呗🐎

首先，Mongoose 的一切始于 Schema³，使用 populate 的重点也在于 Schema 中的设置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


const mongoose = require('mongoose');
const Schema = mongoose.Schema;
const authorSchema = new Schema({
"author": String,
"age": Number,
"books": [{
type: Schema.Types.ObjectId,
ref: 'Book' // 关联的Model
 }]
});
module.exports = mongoose.model("Author", authorSchema, "authors"); // 分别为Model名、Schema、数据库中集合名

在接口中使用populate():

1
2
3
4
5
6
7
8
9


router.get('/getAuthorInfo_p', async (req, res) => {
let result = await Author.find({
"author": "Zander"
}).populate("books");
res.json({
status: 200,
result: result
})
})

返回数据：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


{
"status": 200,
"result": [
{
"books": [
{
"_id": "5dccfcb5a3fab06c89020c8d",
"name": "代码的弱点"
},
{
"_id": "5dccfd30a3fab06c89020caa",
"name": "代码与六便士"
},
{
"_id": "5dccfda6a3fab06c89020cc3",
"name": "代码失格"
}
],
"_id": "5dccfc3aa3fab06c89020c65",
"author": "Zander",
"age": 18
}
]
}

对比

1. 灵活性

现在可以观察到的就是 aggregate 灵活的点在于可以更改关联查询后返回数据的 key（返回数据中的bookList），而 populate 返回数据的 key 只能是原来的字段名（返回数据中的books）。值得一提的是 aggregate 更擅长在聚合管道中..对数据进行二次处理..，比如$unwind拆分、$group分组等等。

2. 功能性

此外，还有一种情况：依旧是上面的数据，如果要根据著作 name 找到著作信息和作者信息，使用 aggregate 的$lookup只需要这样就做到了😏：

1
2
3
4
5
6


$lookup: {
from: "authors",
localField: "_id",
foreignField: "books",
as: "author"
}

然而 populate：“我太难了！”

是的，它做不到这种使用_id实现的..反向关联..查询，通俗点讲，Mongoose 不允许你这样写：

1
2
3
4
5
6
7


const bookSchma = new Schema({
"_id": { // 不能这样写🙅‍♂️
 type: Schema.Types.ObjectId,
ref: 'Author'
},
"name": String
});

如果你执意要尝试，那么这是你的下场🙃：

1
2
3
4
5
6
7
8
9


{
"status": 200,
"result": [
{
"_id": null,
"name": "代码的弱点"
}
]
}

populate 是将一个集合的_id和另一个集合的非_id字段进行关联的，但是 Mongoose 4.5.0版本以后提供了与 aggregate 功能写法都非常类似的virtual()方法，这里不做详述了，有这个需求我用 aggregate 它不香么？🤨

3. 代码简洁度

大概知道了它们的使用方法和适用场景后再来看看其它方面，比如为什么要重构之前完成的 aggregate 接口🥶。刚入职经验不足拿来别人的代码就依葫芦画瓢，画出来的「瓢」是这样的：

一方面是大量的回调函数，一方面是 aggregate 繁杂的写法，导致代码大量冗余，可读性也极差，现在重构后优雅的「葫芦」：

4. 性能方面

看完了外表再说说内在——查询性能，populate 实际是DBRef⁴的引用方式，相当于多构造了一层查询。比如有10条数据，在find()查询到了主集合内的10条数据后会再进行populate()引用的额外10条数据的查询，性能也相对的大打折扣了。这里有位大佬对aggregate()和find()进行了性能上的对比，结论也显而易见——比 find 查询速度都快的 aggregate 比关联查询的 find + populate 定是有过之而无不及了。

总结

	aggregation	populate
灵活性	⭐️⭐️⭐️⭐️⭐	⭐️
反向关联	⭐️⭐️⭐️⭐️⭐️	⭐️⭐️
功能性	⭐️⭐️⭐️⭐️⭐️	⭐️⭐️⭐️
代码简洁度	⭐️	⭐️⭐️⭐️⭐️⭐️
查询性能	⭐️⭐️⭐️⭐️	⭐️⭐️

综合来看，aggregate 在多集合关联查询和对查询数据的二次处理方面更优，而 populate 更适合简单的正向关联关系且其形成的代码样式较优雅，可读性高而易于维护，性能方面的考究对日常开发中的普通应用来说则大可忽略不计。

技术的使用无不建立在需求和场景之上，不抱令守律，不因噎废食，知变通，知择优，毕竟技术只是工具，目的才是关键。

macOS 升级 Catalina 后根目录无权限问题

xuezenghui6@gmail.com (Zander Hsueh) — Wed, 30 Oct 2019 13:31:18 +0800

Bug 复现

就在昨天..快快乐乐..升级 macOS Cataline 之后，一切都还是那么舒服，直到刚才需要启动 MongoDB 数据库，就在我自信地在 shell 中输入mongod之后报了个错，看都没看就sudo mongod，嗯？？？

Data directory /data/db not found., terminating

谁把我 dbpath 目录删了？？？重建呗——sudo mkdir /data，大问题来了：

mkdir: data: Read-only file system

遂尝试各种增加权限方法，无效，直到看到了一篇文章讲到问题出在新系统 Catalina 默认不允许往系统分区写文件，亲试解决方法有效后在此记录下步骤。

Figure out

关闭本机SIP(系统完整性保护)

终端中输入csrutil status后返回System Integrity Protection status: enabled.说明 SIP 处于开启状态。

重启电脑，按住command + R直至进入系统恢复界面，然后点击实用工具选择终端：

输入csrutil disable关闭SIP：

权限获取

重新启动电脑，shell 中输入sudo mount -uw /，然后就有权限在根目录创建文件夹了，MongoDB 的启动问题得解。

如果此时还是报错没有权限，请再尝试以下步骤：

桌面使用shift + command + C前往电脑磁盘
右击 Macintosh HD 磁盘选择显示简介
在共享与权限中添加自己的用户为管理员并设置读与写权限并应用到包含的项目
重新创建文件夹

因为使用 MongoDB 期间会更改 /data/db 文件，所以不能重新开启 SIP，否则还是会报错权限问题，而 SIP 一直处于关闭状态实际上会导致电脑有一定的安全隐患，详情请查阅关于 Mac 上的系统完整性保护，希望后续能有更好的解决途径吧。

~~最后，Catalina 真香～~~

2019/12/24更：恕我直言，以上解决办法真的是弱爆了，因为每重启一次 Mac 就需要执行一遍权限获取的操作，苦不堪言。更好的解决办法是在执行启动 MongoDB 的命令时指定 /data/db 目录位置，但更一劳永逸的办法是使用 Docker 启动 MongoDB。

Catalina 依然挺香的😎～

踩坑 MongoDB 条件查询

xuezenghui6@gmail.com (Zander Hsueh) — Wed, 16 Oct 2019 00:00:00 +0800

Bug 复现

后台使用 Node.js + Express + Mongoose

项目中需要用到 MongoDB 的条件查询$gt，用法也很简单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


SinglePrints.find({
"last_day_click": {
$gt: thisPrint // 查询大于thisPrint值的数据
 }
}, (err, data) => {
if (err) {
console.log(err);
return;
}
res.json({
status: 200,
result: data
})
})

更新于2019/11/9，发誓..再也不写回调..后的我回来更新此处代码了🌚：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


router.get('/', async (req, res) => {
let thisPrint = req.query.thisPrint;
let result = await SinglePrints.find({
"last_day_click": {
$gt: thisPrint // 查询大于thisPrint值的数据
 }
});
return res.json({
status: 200,
data: result
});
})

而且强大的地方还在于无论这里的thisPrint类型是Number还是String，MongDB 会自动识别为Number类型来和数据库中的字段进行比较。

那么问题出在哪里呢？当thisPrint的值小于1000时，查询的结果是没有任何问题的，但如果大于1000条件筛选就会失效。

Figure out

这种看似和筛选条件大小有关系的 bug 实则非也，而是和数据库中需要比对的字段的类型有关，也就是上述例子中last_day_click存储类型的原因。当类型为String时就会发生偶尔失效的状况，这就要求在存储这个字段的时候将它存为Number类型，即在 Mongoose 的Schema中将其类型定义为Number。

D3.js

xuezenghui6@gmail.com (Zander Hsueh) — Sun, 13 Oct 2019 00:00:00 +0800

需要了解的几个概念

数据可视化

基于Web的数据可视化指的是在网页中显示数据统计报表，从而可以更直观地了解数据的走向和趋势，如图表、图谱、地图、关系图、立体图。

数据可视化的展现方式从以往的 Flash 技术、IE 的 vml 语言发展至如今规范统一的 HTML5 技术点——Canvas 和 SVG。

SVG

可缩放矢量图形，基于 XML。

SVG 图形练习：SVG 图形实例

要使用 SVG 就要考虑到浏览器的兼容问题，Can I Use 是一个查看浏览器兼容状态的强力工具

D3.js

简介

Data Driven Documents，基于数据驱动文档的 JavaScript 库，用于网页作图、生成互动图形，是一个优秀的可视化库。D3.js 不需要你使用哪个特定的框架，也就是说只要能写 JavaScript 就能使用 D3.js，当然是要在浏览器兼容的前提下了。

优势

堪称 SVG 中的 jQuery，操作 SVG 极为方便，当然 Canvas 也支持

截止目前来说，D3 是操作 SVG 最为方便的一个库，堪比 jQuery 和 JavaScript 的关系，当然这不是说 D3 只能操作 SVG，在 v3 之后的 v4 版本开始 D3 就已经支持 Canvas 了，但是支持不代表擅长，主要的处理目标还是 SVG。
相比于 Echarts 这种框架式工具来说，D3.js 的自由度更高，但相对的学习成本也会变高

chart 类的工具（Highchart、Echarts）固然简单易上手，但是这类都是“框架式工具”，和“库”区别还是比较大的。举个例子，你需要装修自家房子，一种方式是提供给你装修会用到所有工具并教会你所有装修方法，装修风格就任君发挥了，还有一种方式就是给你出几个样本房，自己从中选择，这就是“库”和“框架式工具”的区别了，所以，玩转 D3 后限制图形样式的就只有你的想象力了。
操作DOM极其强大

毫不夸张的说，如果你学习过 jQuery，D3 你已经会了⅓。甚至网上有人说 D3 可以替代 jQuery，虽然不现实，但这个说法确实得益于 D3 极强的操作 DOM能力。

入门实例——直方图

1. 新建一个 HTML5 文件

1
2
3
4
5
6
7
8
9


<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>D3.js</title>
</head>
<body>
</body>
</html>

2. 引入 D3.js

1

<script src="http://d3js.org/d3.v3.min.js"></script>

3. 创建 div 用来展示 SVG

1

<div id='svg'></div>

4. 使用 D3.js 的语法绘制 SVG

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


const dataset = [223, 34, 55, 66, 99, 276, 123]; // 定义数据
const height = 400; // 定义SVG的高
const width = 400; // 定义SVG的宽
const svg = d3.select("#svg").append("svg")
.attr("height", height)
.attr("width", width);
const padding = {
top: 20,
left: 20,
right: 20,
bottom: 20
};
const rectStep = 35; // 定义间隔
const rectWidth = 30; // 定义矩形宽度
svg.selectAll("rect").data(dataset).enter().append("rect") // 操作矩形
 .attr("fill", "yellow") // 填充颜色
 .attr("x", (d, i) => padding.left + i * rectStep) // 设置矩形x轴坐标
 .attr("y", (d, i) => height - padding.bottom - d) // y轴坐标
 .attr("width", rectWidth) // 矩形宽度
 .attr("height", d => d); // 高度

const text = svg.selectAll("text").data(dataset).enter().append("text") // 添加文本
 .attr("fill", "pink") // 文本颜色
 .attr("font-size", "16px")
.attr("text-anchor", "middle") // 居中显示
 .attr("x", (d, i) => padding.left + i * rectStep)
.attr("y", (d, i) => height - padding.bottom - d)
.text(d => d) // 文本内容
 .attr("dx", rectWidth / 2) // x轴偏移量
 .attr('dy', "-10px") // y轴偏移量

⚠️注意：

矩形的 x、y 坐标以矩形的左上角为中心点

SVG 填充背景颜色使用的是fill属性

矩形之间的间隔为 x 轴的差值

涉及的API：

API	含义	示例
.select	选择元素	d3.select("#id")
.selectAll	选择多个元素	d3.selectAll("#id")
.append	添加元素	.append("svg")
.attr	添加属性	.attr("width","400")
.data	绑定数据	.data([45,64])
.enter	当DOM元素数量少于data的数量时，自动创建元素	.enter()
.text	设置文本内容	.text(d => d)

比例尺和坐标轴

比例尺

先来回顾一下上次直方图中是怎样设置“柱子”的高度的：

1
2
3
4
5
6


svg.selectAll("rect").data(dataset).enter().append("rect") // 操作矩形
 .attr("fill", "yellow") // 填充颜色
 .attr("x", (d, i) => padding.left + i * rectStep) // 设置矩形x轴坐标
 .attr("y", (d, i) => height - padding.bottom - d) // y轴坐标
 .attr("width", rectWidth) // 矩形宽度
 .attr("height", d => d); // 高度

对的，这里是直接使用数值的大小来表示“柱子”的高度，你可能会表示：显示的高度肯定是和数值的大小有关系啊！对！问题就在这个..关系..上，如果一定是这样..一对一..的关系，那数值是这样呢：[ 2.5 , 2.1 , 1.7 , 1.3 , 0.9 ]，这样呢：[ 2500, 2100, 1700, 1300, 900 ]。

这样的数据可视化是毫无可读性、也是绝不可取的，所以需要一种..计算关系..，能够将某一区域的值映射到另一区域，其大小关系不变，这就是 D3 中的一个重要概念——比例尺。

`scaleLinear()`线性比例尺

线性比例尺中，定义域和值域都是连续的一一对应关系。

例子

1

var dataset = [1.2, 2.3, 0.9, 1.5, 3.3];

需求
- 将最小的值映射为0，将最大的值映射为300。

定义比例尺：

1
2
3
4


const linear = d3
.scaleLinear()
.domain([d3.min(dataset), d3.max(dataset)])
.range([0, 300])

结果

1
2
3


linear(0.9) // 输出:0
linear(2.3) // 输出:175
linear(3.3) // 输出:300

解释
- .domain()为定义域，.range()为值域
- d3.min()和d3.max()返回数组中的最小值和最大值

`scaleOrdinal()`序数比例尺

输入域和输出域都是离散的数据，不连续，其数据是序数关系。

例子

1
2


const dataset = [45, 34, 145, 11, 78];
const color = ['pink', 'blue', 'yellow', 'black', 'green'];

需求
- 45对应 pink，34对应 blue，以此类推。

定义比例尺

1
2
3
4


const ordinal = d3
.scaleOrdinal()
.domain(dataset)
.range(color)

结果

1
2
3


ordinal(45) // 输出:color
ordinal(145) // 输出:yellow
ordinal(78) // 输出:green

v3 以下版本和 v3 以上版本比例尺的写法不同，详情请参阅官方文档。

坐标轴

基本每种图表都需要坐标轴，但是 SVG 中并没有现成的元素，而是需要由其它图形来组成——..刻度.. 和 ..直线..。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68


// 引入D3的v5版本：`<script src="https://d3js.org/d3.v5.min.js"></script>`

const dataset = [223, 34, 55, 66, 99, 276, 123]; // 定义数据
const height = 400; // 定义SVG的高
const width = 400; // 定义SVG的宽
// const
const svg = d3.select("#svg").append("svg")
.attr("height", height)
.attr("width", width);
const padding = { // 定义间距
 top: 50,
left: 50,
right: 50,
bottom: 50
};
const rectStep = 35; // 定义间隔
const rectWidth = 30; // 定义矩形宽度
const xAxisWidth = width - padding.left - padding.right; // x轴长度
const yAxisWidth = height - padding.top - padding.bottom; // y轴长度
const xScale = d3 // x轴比例尺
 .scaleBand() // 序数比例尺
 .domain(dataset.map((d, i) => i)) // 定义域
 .range([0, xAxisWidth]) // 值域
 .padding(0.1); // 坐标轴间距

const yScale = d3 // y轴比例尺
 .scaleLinear() // 线性比例尺
 .domain([0, d3.max(dataset)]) // 定义域
 .rangeRound([yAxisWidth, 0]); // 值域

const genRect = obj => { // 设置矩形的函数
 obj.attr("fill", "yellow") // 填充颜色
 .attr("x", (d, i) => padding.left + xScale(i)) // 设置矩形x轴坐标
 .attr("y", (d, i) => height - padding.bottom - (yScale(0) - yScale(d))) // y轴坐标
 .attr("width", xScale.bandwidth()) // 矩形宽度
 .attr("height", d => yScale(0) - yScale(d)); // 高度
}
const genText = obj => { // 设置文本的函数
 obj.attr("fill", "pink") // 文本颜色
 .attr("class", "number")
.attr("font-size", "16px")
.attr("text-anchor", "middle") // 居中显示
 .attr("x", (d, i) => padding.left + xScale(i)) // 设置矩形x轴坐标
 .attr("y", (d, i) => height - padding.bottom - (yScale(0) - yScale(d))) // y轴坐标
 .text(d => d) // 文本内容
 .attr("dx", xScale.bandwidth() / 2) // x轴偏移量
 .attr('dy', "-10px") // y轴偏移量
}
const init = dataset => { // 初始化数据函数
 genRect(svg.selectAll("rect").data(dataset).enter().append("rect"));
genText(svg.selectAll("text").data(dataset).enter().append("text"));
}
init(dataset);
const xAxis = d3.axisBottom(xScale); // x轴
const gx = svg // 存放x轴的容器
 .append("g")
.attr("transform", `translate(${padding.left},${height-padding.bottom})`); // 默认显示在上方显示，要使他偏移到下面
gx.call(xAxis); // 将x轴放进容器

const yAxis = d3.axisLeft(yScale); // y轴
const gy = svg
.append("g")
.attr("transform", `translate(${padding.left},${height-yAxisWidth-padding.bottom})`); // 默认显示在上方显示，要使他偏移到下面
gy.call(yAxis);

用户交互与力导向图

交互式操作

用户交互指的是用户输入了某种指令，程序接收到后做出了某种响应，而 D3.js 中的用户交互当然指的是用户与可视化图表的交互操作了。

例如鼠标移动至图形上时候图形的变色、变形、文字提示，或是点击变大缩小等等，而最经典的运用就是..力导向图..了。

厉害的交互式图表案例

添加交互

D3 中使用事件监听函数.on(type, function)为元素添加交互事件。

参数 type 为事件类型，下表为常见的事件，参数 function 为事件处理函数

事件名	含义
鼠标操作
click	鼠标单击
mouseover	鼠标进入
mouseout	鼠标移出
mousemove	鼠标移动(需节流处理)
mousedown	鼠标按下
mouseup	鼠标松开
dblclick	鼠标双击
键盘操作	按住不放会持续触发
keydown	键盘按下
keyup	键盘释放
keypress	键盘按下字符键
触屏操作
touchstart	触摸屏幕
touchmove	触摸点移动
touchend	离开屏幕

d3.select(this)可以直接选择触发事件的元素，但前提是事件处理函数不使用箭头函数
每个select的元素都可以添加.on()事件监听函数

布局

布局的作用是将不适合用于绘图的数据转换为适合用于绘图的数据，简而言之——数据转换。

D3（v4 以上版本）提供了以下12种布局：

布局( v3 与 v4以上版本写法不同)	API
饼状图(Pie)	d3.layout.pie
力导向图(Force)	d3.forceSimulation
弦图(Chord)	d3.layout.chord
树状图(Tree)	d3.tree
集群图(Cluster)	d3.cluster
捆图(Bundle)	d3.layout.bundle
打包图(Pack)	d3.pack
直方图(Histogram)	d3.layout.histogram
分区图(Partition)	d3.partition
堆栈图(Stack)	d3.layout.stack
矩阵树图(Treemap)	d3.treemap
层级图(Hierarchy)	d3.hierarchy

力导向图

建立在力学模型基础上的一种特殊的图表，常用来呈现复杂的关系网络。由节点和连线组成，节点和连线都被施加了力的作用，根据力来计算节点和连线的运动轨迹。

实现

整体思路

定义数据（节点数据和连线数据）
定义SVG画布
设置力导向图布局
绘制节点（circle）、连线（line）、描述文字（text）和关系文字（text）
监听力导向图的tick事件，每运动一帧重新设置节点坐标、连线起始结尾坐标、描述文字坐标和关系文字坐标

核心代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161


const nodes = [{ name: "Zander" }, { name: "Annie" }, { name: "Anna" },
{ name: "Doris" }, { name: "Linda" }, { name: "Censek" }, { name: "Paul" }];
const edges = [{
source: 0, // 数组下标
 target: 4,
relation: "Cherry组队友"
},
{
source: 0,
target: 6,
relation: "上下属"
},
{
source: 1,
target: 3,
relation: "Alice组队友"
},
{
source: 1,
target: 6,
relation: "上下属"
},
{
source: 2,
target: 6,
relation: "上下属"
},
{
source: 2,
target: 5,
relation: "两口子"
},
{
source: 3,
target: 6,
relation: "上下属"
},
{
source: 4,
target: 6,
relation: "上下属"
},
{
source: 5,
target: 6,
relation: "上下属"
},
{
source: 2,
target: 4,
relation: "相爱相杀"
},
{
source: 3,
target: 5,
relation: "室友"
}
];
const height = 800;
const width = 800;
const padding = {
top: 50,
left: 50,
bottom: 50,
right: 50
};
// svg画布
let svg = d3
.select("#svg")
.append("svg")
.attr("height", height)
.attr("width", width);
// 设置力导向图布局和参数
let force = d3
.forceSimulation() // 指定为力导向图布局
 .nodes(nodes) // 设置节点
 .force("link", d3.forceLink(edges).distance(200)) // 设置连线和连线的长度
 .force("charge", d3.forceManyBody) // 添加多体力（吸力、斥力等组合起来的高阶函数）
 .force(
"center", // 设置力中心点
 d3
.forceCenter() // 创建一个力中心
 .x((width - padding.left - padding.right) / 2) // x坐标
 .y((height - padding.top - padding.bottom) / 2) // y坐标
 );
console.log(nodes); // 数据改变
// 绘制节点
var circles = svg
.selectAll("circle")
.data(nodes)
.enter()
.append("circle")
.attr("r", 10)
.style("fill", "yellow");
// 绘制连线
var lines = svg
.selectAll("line")
.data(edges)
.enter()
.append("line")
.style("stroke", "green")
.style("stroke-width", 1);
// 添加描述
var text = svg
.selectAll("text")
.data(nodes)
.enter()
.append("text")
.style("font-size", "12px")
.style("fill", "#000")
.attr("dx", 0)
.attr("dy", 0)
.text(d => d.name);
// 添加关系
var relations = svg
.selectAll(".relation")
.data(edges)
.enter()
.append("text")
.style("fill", "red")
.style("font-size", "11px")
.attr("class", "relation")
.attr("dx", 0)
.attr("dy", 0)
.text(d => d.relation);
force.on("tick", () => { // 监听力导向图每运动一帧
 lines
.attr("x1", d => d.source.x)
.attr("y1", d => d.source.y)
.attr("x2", d => d.target.x)
.attr("y2", d => d.target.y);
circles
.attr("cx", d => d.x)
.attr("cy", d => d.y)
.call( // 将拖拽行为加入到节点上
 d3
.drag() // 设置拖拽行为
 .on("start", dragStarted) // 拖拽开始
 .on("drag", dragging) // 拖拽中
 .on("end", dragEnded) //拖拽结束
 );
text.attr("x", d => d.x).attr("y", d => d.y);
relations
.attr("x", d => (d.source.x + d.target.x) / 2) // x坐标为连线中间点x坐标
 .attr("y", d => (d.source.y + d.target.y) / 2); // y坐标为连线中间点y坐标
});
function dragStarted(d) { // 拖拽开始事件处理函数
 if (!d3.event.active) force.alphaTarget(0.3).restart(); // 设置力的衰减系数α（范围[0, 1]，值越大移动速度越高，并重新布局该区域
 d.fx = d.x; // d.fx为静止时的坐标，d.x为初始坐标
}
function dragging(d) { // 拖拽中事件处理函数
 d.fx = d3.event.x; // d3.event.x为拖动时的坐标
 d.fy = d3.event.y;
}
function dragEnded(d) { // 拖拽结束事件处理函数
 if (!d3.event.active) force.alphaTarget(0);
d.fx = null;
d.fy = null;
}
}

绘制热点图

没事儿画啥地图？

比如现有一需求：
- 在吃鸡地图中标示出哪里跳伞的人多及哪里跳伞的人少，然后就可以根据这个图大概分析出跳哪里落地成盒的几率更小🌚。

正经点儿，实际业务需求：
- 在中国地图上显示出百星23个自有制作中心、16个驻场制作中心、39个外包服务站点所在的地理位置(实力打广告🤨)，并通过点的大小、亮度等体现出不同制作中心的业务量高低。
没错，热点图(又称地图散点图)是这类需求的标准解决方案，其可通过在地图上不同区域使用不同的标志来呈现不同区域的关注程度，使数据清晰明了地呈现在人眼前。

准备工作

1. 中国地理信息文件——GeoJSON

GeoJSON是用于描述地理空间信息的数据格式，包括地图上的所有要素，如经纬度、点、线、面、特征等，格式为 JSON 格式。

网上搜索 china.json 一大堆😏，但是要注意格式要符合 GeoJSON 标准

2. 球形➡️平面投影——d3-geo

经纬度不能直接用于绘图，需要转换为平面坐标，D3 中提供了丰富的投影函数来处理球面坐标和经纬度运算。

安装：npm install d3-geo d3-array --save

3. 配色方案

安装：npm install d3-scale-chromatic --save

绘制地图

1. 按需导入类库

1
2
3
4
5


<!-- HTML结构 -->
<div>
<div id="svg"></div>
<div id="hover"></div>
</div>

1
2
3


// .vue文件中
import * as geo from "d3-geo";
import * as d3Color from "d3-scale-chromatic";

2. 定义 SVG 画布和投影函数

1
2
3
4
5
6


// 投影函数
const projection = geo
.geoMercator() // 球形墨卡托投影
 .scale(550) // 投影的比例因子，可按比例放大投影
 .center([105, 38]) // 设置中心点的经纬度为中国地图中心点
 .translate([width / 2, height / 2]); // 将投影偏移至设SVG中心

3. 创建路径生成器和颜色比例尺

1
2


const path = geo.geoPath(projection);
const colors = d3.scaleOrdinal(d3Color.schemeBrBG[11]);

4. 获取 GeoJSON 数据，生成地图

此处为重中之重，要使用 D3.js 提供的d3.json()方法获取地理信息文件，官方文档表明此方法根据指定的 url 创建一个 JSON 文件请求，这就要求不能使用本地的 JSON 文件而要搭建服务器返回数据。本案例使用 Express + MongoDB 搭建了简单的服务器返回地理信息数据。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


async function getJson() { // 使用d3.json()方法拿到GeoJSON数据
 const result = await d3.json("/api/allData");
// const result = await d3.json("../../static/china.json"); // d3.json()不可访问本地文件
 const data = result.result; // 拿到数据，Object类型
 console.log(data);
return data;
}
getJson().then(data => {
svg
.selectAll("path")
.data(data.features) // 绑定地理特征数据
 .enter()
// .append("path")
 .insert("path", "g")
.attr("d", path)
.attr("fill", function (d, i) { // 加入颜色比例尺
 return colors(i);
})
.attr("stroke", "rgba(255, 255, 255, 1")
.attr("stroke-width", 1);
});

使用append("path")的话 DOM 结构中 path 元素会处于 g 元素之前，导致 path 覆盖 g 元素，原因是 D3 中元素的层级是由元素创建的先后顺序来决定的。

定位城市坐标

1. 定义城市坐标数据

1
2
3
4
5


const places = [
{ name: "北京制作中心", log: "116.54", lat: "39.82" }, // log为经度， lat为纬度
 { name: "西安制作中心", log: "108.84", lat: "34.21" },
{ name: "沈阳制作中心", log: "123.39", lat: "41.86" }
];

2. 标点并绘制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


const location = svg
.selectAll("g")
.data(places)
.enter()
.append("g")
.attr("transform", d => {
const coord = projection([d.log, d.lat]); // 将经纬度转化为页面坐标
 console.log("coord", coord);
return `translate(${coord[0]},${coord[1]})`;
});
location
.append("circle")
.attr("r", 4)
.attr("fill", "yellow");

3. 加入动画

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


const hover = d3.select("#hover");
location
.on("mouseover", function (d) {
hover
.html(d.name)
.style("position", "fixed")
.style("color", "blue")
.style("left", d3.event.pageX - 45 + "px")
.style("top", d3.event.pageY - 40 + "px")
.style("opacity", 1);
d3.select(this)
.select("circle")
.transition()
.duration(500)
.attr("r", 8);
})
.on("mouseout", function () {
hover.style("opacity", 0);
d3.select(this)
.select("circle")
.transition()
.duration(1000)
.attr("r", 4);
});

🎱案例 GitHub 地址：https://github.com/Xuezenghuigithub/D3.js_china_map

References & Resources

常用 CSS 样式总结

xuezenghui6@gmail.com (Zander Hsueh) — Wed, 09 Oct 2019 00:00:00 +0800

标题左右横线

1

<div class="title"></div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


.title {
position: relative;
font-size: 18px;
line-height: 18px;
text-align: center;
top: 60px; /* 标题与顶部距离 */
}
.title:before {
content: "";
position: absolute;
width: 28px; /* 横线长度 */
height: 1px; /* 横线粗细 */
top: 50%;
background-color: #ddd; /* 横线颜色 */
left: 28%; /* 左横线与文字距离 */
}
.title:after {
content: "";
position: absolute;
width: 28px;
height: 1px;
top: 50%;
background-color: #ddd;
right: 28%; /* 右横线与文字距离 */
}

微信小程序——多行文本展开/收起

1
2
3
4
5


<!-- .wxml文件 -->
<text class="text {{ellipsis?'ellipsis':'unellipsis'}}">北京百星电子系统有限公司（以下简称百星公司）成立于1995年，是全外资的高科技企业，运用“云”技术理念，为客户提供专业的外包服务解决方案，对可变数据的抓取、生成电子文档、存储、传输、调阅、发送、打印等各个阶段实现全面优化管理与监控。截至目前，已在全国主要省会城市建立12个自有打印制作中心，与客户合作建立31个外包服务站点。</text>
<view bindtap='ellipsis' class="ellipsis_arrow">
<image class="ellipsis_img" src="{{ellipsis?'/images/down.png':'/images/up.png'}}"></image>
</view>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


// .wxss文件
.text {
display: -webkit-box; /* 自适应盒模型 */
text-overflow: ellipsis; /* 文字溢出显示省略号 */
-webkit-box-orient: vertical; /* 内容水平排列 */
font-size: 24rpx;
line-height: 40rpx;
color: rgb(135, 135, 135);
padding: 0 20px;
padding-top: 60px;
overflow: hidden; /* 必须设置溢出隐藏 */
}
.ellipsis {
-webkit-line-clamp: 5; /* 收起显示的文字行数 */
}
.unellipsis {
-webkit-line-clamp: 0; /* 展开后显示全部 */
}
.ellipsis_arrow { /* 小箭头样式 */
width: 30px;
display: block;
margin: auto;
margin-top: -4px
}
.ellipsis_img { /* 箭头图片大小 */
width: 30px;
height: 30px;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// .js文件

Page({
data: {
ellipsis: true // 默认收起
 },
ellipsis: function() { // 点击小箭头触发事件
 var value = !this.data.ellipsis;
this.setData({
ellipsis: value
})
}
)}

微信小程序——时间轴组件

timeline 组件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


<!-- timeline.wxml -->
<view class="time_line">
<!-- 左边时间轴 -->
<view class='leftView'>
<view class="outRoundView"></view>
<view class='leftLine'>
</view>
</view>
<!-- 右边文字 -->
<view class='rightContent'>
<slot name="rightChilren"></slot>
<text wx:if="{{axisTitle!=''}}" class='rightTitle'>{{axisTitle}}</text>
<block wx:if="{{textArray.length>0}}">
<text wx:for="{{textArray}}" wx:key="unique" class='rightText'>{{item}}</text>
</block>
<text class='rightText'>{{axisText}}</text>
</view>
</view>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


/* timeline.wxss */
.timeline {
display: flex;
flex: 1;
padding: 0px 20px;
background-color: #fff;
}
.leftView {
display: flex;
flex-direction: column;
}
.outRoundView {
width: 9px;
height: 9px;
border-radius: 50%;
background: #fff;
border: 2px solid #999;
}
.leftLine {
display: flex;
flex: 1;
width: 1px;
margin-left: 6px;
padding-bottom: 6px;
background: #dadada;
}
.rightContent {
display: flex;
flex: 1;
flex-direction: column;
margin-top: -6px;
margin-left: 15px;
padding-bottom: 24px;
}
.rightTitle {
font-size: 32rpx;
line-height: 22.5px;
color: rgba(0, 0, 0, .7);
}
.rightText {
font-size: 14px;
color: #999;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


// timeline.js

Component({
/**
 * 组件的属性列表
 */
properties: {
isShowLeftLine: { // 是否显示时间轴
 type: Boolean,
value: true
},
axisTitle: { // 标题
 type: String,
value: ''
},
axisText: { // 文字
 type: String,
value: ''
},
textArray: { // 多行文字
 type: Array,
value: []
}
}
})

1
2
3
4


// timeline.json
{
"component": true
}

使用组件的页面：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- .html文件 -->
<view>
<timeLine axisTitle="1995年" axisText="Bel-Star【北京百星电子系统有限公司】成立于北京"></timeLine>
<timeLine axisTitle="2000年" axisText="荣获Oce亚太地区打印机销售冠军"></timeLine>
<timeLine axisTitle="2005年" textArray="{{textArray2005}}"></timeLine>
<timeLine axisTitle="2008年" axisText="发表EOMO保单云端处理生产管理平台"></timeLine>
<timeLine axisTitle="2015年" textArray="{{textArray2015}}"></timeLine>
<timeLine axisTitle="2017年" textArray="{{textArray2017}}"></timeLine>
<timeLine axisTitle="2019年" textArray="{{textArray2019}}"></timeLine>
</view>

1
2
3
4
5
6
7


// .json文件

{
"usingComponents": {
"timeLine":"/components/timeLine/timeLine"
}
}

将 Hexo 博客部署至 Netlify

xuezenghui6@gmail.com (Zander Hsueh) — Sun, 06 Oct 2019 23:04:22 +0800

前言

其实这个博客总共也才断断续续捣鼓了 fortnight，被好奇心驱使着到处搜集相关资料，浏览研究了很多“巨人”的文章和令人惊艳的个人博客。最开始是按 Hexo 的文档将博客部署在 GitHub Pages 上的，但是这个国庆让我感受到了“墙”深深的恶意——几乎所有的科学上网服务器节点都失效了，访问 GitHub 速度极慢，所以部署于 GitHub Pages 的博客加载速度就非常慢(之前也快不到哪儿去🙄)。然后了解到了 Netlify 的一些特性，决定将博客部署到 Netlify 上。

Netlify简介

Netlify 是一个静态网站自动化部署系统，可快速将静态网站直接构建部署，不需要你提供静态资源服务器。Netlify 基于 JAMstack 架构，即客户端 JavaScript、可重用 API 和预构建 Markup，这是一种现代化、未来化的构建网站的方法，可以提供更好的性能(全球 CDN )、安全性(HTTPS)和更好的开发体验(持续部署及Git集成)。且 Netlify 提供的功能和服务相比 GitHub Pages 可太强大了😏——绑定域名、页面重定向、静态资源文件压缩、免费的 HTTPS 等等，而且文档翻译过来也比较清晰流畅…

优势

Simply Push to Deploy

支持热部署，只需要将代码 push 到 Git 远程仓库即可自动构建及更新。
Free automatic HTTPS

支持自定义域名，提供免费 HTTPS ，可上传域名证书。
Never have to leave Terminal

可在终端中操作 Netlify。

部署步骤

虽然 Netlify 没有中文文档，但也别被它的全英文唬住，部署的步骤还是比较简单的，但是它提供的强大功能我也并没有尝试很多，还在持续摸索总结中。

Netlify 支持两种部署方式，直接拖拽站点文件至页面部署和连接 Git 方式的持续部署，因为之前博客是将 Hexo 生成的public文件夹部署至 GitHub Pages 的，为了写博客的便利性我还是选择采用 Git 方式部署，这样部署成功后还是可以本地hexo g➡️hexo d实现博客的部署更新。

首先直接使用 GitHub 账号登录 Netlify，点击界面中的New site from Git按钮：

第一步，选择连接 GitHub：

需要注意的是进行此步骤时尽量关闭所有的科学上网工具，安安分分使用内网，否则..或将..导致网络请求无法连接 GitHub，从而迟迟不跳出授权的页面。鬼知道我当时费了多少周折寻求解决办法结果花费一秒的时间关掉 Shadowsocks 就成了？？？🙃

授权，直接按照默认的选项点击Install即可：

第二步，选择博客的仓库，比如我这里的 Xuezenghuigithub.github.io 仓库：

第三步，配置选项、构建部署：

接着等待片刻就部署成功了🍺，点击笑脸😊选项卡即可访问部署成功的网站：

绑定域名，设置 DNS

首先肯定得申请域名了，很多前辈推荐在狗爹 GoDaddy 上购买域名，言之划算且不需要繁琐的域名备案，但是折腾了一番发现中国内地在 GoDaddy 上购买.com域名是不能使用支付宝支付的，其它支付方式又很麻烦，故弃之选择在阿里云上购买域名，操作方便价格无差——真香！(叮～支付宝到账0.5元！)

有了域名后点击部署项目的 Domain setting，在 Custom domains 内直接输入域名即可，然后去 DNS 设置面板：

按照面板内步骤在阿里云域名控制台修改域名的 DNS 服务器，修改成功后域名后就有了上图中绿色的Netlify DNS标志，这时域名就由 Netlify 管理了，DNS 解析也会自动配置，省事ing。

设置HTTPS

上面说到了，Netlify 是支持免费 HTTPS 的，只需要在 Domain setting 的 HTTPS 设置中点击按钮即可为网站添加 Netlify 提供的免费的 Let's Encrypt 证书，当然，阿里云也提供了免费的 SSL 证书，不嫌麻烦的话也可以使用自定义的证书，但本质上都是为了域名前的那个🔒，区别不大。

要说明的是，虽然已经有了 HTTPS，但访问博客后域名前是❗️而不是🔒，提示与网站之间建立的连接并非完全安全，这是因为网站内包含了其它的非 HTTP 请求，比如七牛云的图片外链等，解决办法就是将博客文章内的 HTTP 链接全部替换为 HTTPS，但说回来这种情况也并不影响正常的浏览访问，而且我这个穷鬼不配拥有七牛云的 HTTPS 格式图片外链🌚。

修改博客相关配置

绑定了自己的域名后相关的功能会失效，比如 Valine 评论会不显示、百度统计获取不到新域名的网站报告等，需要对相关配置加以修改。

博客配置

修改博客的 URL 配置：

1
2
3
4


# 文件位置：blog/_config.yml
# URL
url: https://blog.xuezenghui.com

Valine 评论系统配置

登入 LeanCloud，进入设置➡️安全中心➡️Web安全域名中添加域名：

https://xuezenghuigithub.github.io/
https://www.blog.xuezenghui.com/
http://www.blog.xuezenghui.com/

协议、域名、端口号必须完全一致，自己申请域名的www不能省略。

百度统计配置

登录百度统计，新增网站，获取代码，将代码中hm.src行?后的字符复制，修改配置：

# 文件位置：blog/_config.yml
# Baidu Analytics ID
baidu_analytics: 123hasdhda8d2u3dhiua

小程序中 PDF 文件的上传及下载

xuezenghui6@gmail.com (Zander Hsueh) — Mon, 30 Sep 2019 00:00:00 +0800

需求

微信小程序中上传 PDF 文件（其它格式文件也可）至服务器（Node.js），并可在后台管理系统（Vue.js）中下载存储的 PDF 文件至本地。

思路

微信小程序中利用现有 API 实现本地文件的上传
后台处理上传过来的二进制数据
存储
Vue 中发送请求获取后台数据并下载至本地

开搞

小程序中上传文件

首先要明确的是小程序中并没有提供可直接选择手机本地资源文件的 API，原因主要在于iOS系统出于保护用户隐私的文件系统，APP 访问不到系统本地的文件，市值2000亿美金的微信也不例外（辣鸡腾讯???🤨）。

但是，微信小程序提供了选择会话中文件的功能，即wx.chooseMessageFile()接口。什么意思呢？就是比如我从电脑上发了一个文件给文件传输助手，那这个 API 就能在小程序中获取到这个文件的信息。获取到的文件信息包括：

path 本地临时文件路径(上传时要用到)
size 文件大小，单位为 B
name 文件名
type 文件类型

这就要求用户上传 PDF 文件时必须将文件先发送到任何会话中，本质上改变了上传本地文件的需求，所以我谨慎地在标题中没有加入..本地..二字。

拿到了文件的信息后使用wx.uploadFile()接口发送请求上传选择好的 PDF 文件至后台，但是要注意的是编译运行前要勾选微信开发者工具中编辑器面板的详情中的不校验合法域名、web-view (业务域名)、TLS 版本以及 HTTPS 证书，原因请查阅小程序官方文档中的域名配置说明。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


// 小程序页面js文件
Page({
data: {
filePath: "", // 文件路径
 filename: "" // 文件名
 },
chooseFile: function() { // 点击选择文件按钮触发事件
 var _that = this;
wx.chooseMessageFile({ // 会话中选择文件API
 count: 1, // 可选文件个数
 type: 'file', // 文件类型
 success(res) { // 选择成功后的回调函数
 var size = res.tempFiles[0].size; // 文件大小
 var filename = res.tempFiles[0].name; // 文件名
 if (size > 4194301) { // 判断文件大小不能大于4M
 wx.showToast({ // 弹框提示
 title: '文件大小不能超过4MB！',
icon: "none",
duration: 2000,
mask: true
})
} else if (filename.indexOf('.pdf') == -1) { // 判断文件格式必须为pdf
 wx.showToast({
title: '文件格式必须为PDF！',
icon: "none",
duration: 2000,
mask: true
})
} else {
_that.setData({
filePath: res.tempFiles[0].path, // 保存文件地址到data
 filename: filename // 保存文件名
 })
}
}
})
},
uploadFile: function(){ // 上传文件
 var _that = this;
wx.uploadFile({ // 本地资源上传到服务器API
 url: 'http://localhost:3000/uploadFile', // 指定服务器接口URL
 filePath: _that.data.filePath, // 本地文件路径，即选择文件返回的路径
 name: 'file', // 上传文件的key，后台要用到
 formData: { // 可额外添加字段，存于请求的body对象中
 'filename': _that.data.filename
},
success(res) {
const data = res.data;
...
}
})
}
})

后台处理数据并存储

后台使用 Node.js + Express

既然已经知道小程序中上传的是二进制文件了那就好办了，multer 中间件是 Node.js 中处理 multipart/form-data类型数据的常用解决方案，中文文档写的也很清晰，建议往下看之前先仔细研读其文档，具体用法这里不再赘述了。

还有一点需要明确——存储 PDF 文件的方式。我们知道，MongoDB 中的 GridFs 支持文件的存储，但是要考虑项目中具体使用情境的影响如上传的文件数量、文件大小、并发量等，为避免文件数据量过大影响数据库存取效率，建议将 PDF 文件的二进制数据存储于..硬盘文件夹..中而不直接存入数据库中(有文件服务器另说)，下载的时候使用 Node.js 的fs模块再读取文件的二进制流就可以了，此时 Node.js 充当的角色就是简单的静态资源服务器。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// uploadFile.js文件
var express = require('express');
var router = express.Router();
var mongoose = require('mongoose');
mongoose.set('useFindAndModify', false);
var multer = require('multer'); // 引入multer中间件
var storage = multer.diskStorage({ // multer磁盘存储引擎
 destination: function (req, file, cb) {
cb(null, 'uploads/') // 指定存储位置，必须手动创建此文件夹
 },
filename: function (req, file, cb) { // 文件重命名
 var filename = req.body.filename; // 读取请求中formData中额外设置的filename
 cb(null, filename) // 将存储的文件重命名
 }
})
var upload = multer({
storage: storage
})
router.post('/uploadFile', upload.single('file'), (req, res, next) => { // 此处的‘file’即小程序中上传文件时指定的name
 // req.file为文件信息
 // req.body为文本域信息
 res.json({
status: 200
})
})
module.exports = router;

此时，小程序中选择好文件后点击上传按钮服务器会把文件的二进制数据存储在代码中指定的 uploads 文件夹中：

下载存储的 PDF 文件至本地

至此，小程序上传 PDF 文件的需求已经完成了。

既然用户上传了文件，我们就要拿到文件的内容，此处使用 Vue 搭建的的简易后台管理系统(说是个系统显然还不够格儿🤪)完成 PDF 文件的下载需求。

先来完成后台接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// upload.js文件中添加
...
var fs = require('fs'); // 引入fs模块处理文件
...
router.post('/downloadFile',(req, res) => { // 返回文件二进制流数据接口
 var filename = req.body.filename;
var file = './uploads/'+ filename; // 请求文件的实际路径
 res.writeHead(200, { // 设置响应头
 'Content-Type': 'application/octet-stream',// 告诉浏览器这是一个二进制文件
 'Content-Disposition': 'attachment; filename=' + encodeURI(filename),// 告诉浏览器这是一个需要下载的文件
 });
var readStream = fs.createReadStream(file); // 得到文件输入流
 readStream.on('data', (chunk) => {
res.write(chunk, 'binary'); // 文档内容以二进制的格式写到response的输出流
 });
readStream.on('end', () => {
res.end();
})
})

Vue 前台发送请求下载文件到本地：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


<!-- 下载文件组件download.vue -->
<template>
<div>
<!-- 使用了vuetify UI框架的组件, Markdown的代码高亮好像不识别了= = -->
<v-btn @click="download">下载pdf到本地</v-btn>
</div>
</template>
<script>
export default {
name: "download",
data() {
return {
filename: 'test.pdf' // 指定要下载的文件名，与后台uploads文件夹中存储的文件名一致
 };
},
methods: {
download() {
this.$axios({
method: "post",
url: "/api/downloadFile", // 请求URL
 data: {
filename: this.filename // 请求参数
 },
responseType: "blob" // 设置返回的数据类型为二进制数据
 })
.then(response => {
this.downloadFile(response); // 将返回结果作为参数调用本地下载文件方法
 })
.catch(error => {});
},
downloadFile(data) {
var _that = this;
if (!data) {
return;
}
let url = window.URL.createObjectURL(new Blob([data.data])); // 后台返回结果data是个对象，其中的data属性才是文件的二进制数据
 let link = document.createElement("a"); // 创建a标签
 link.style.display = "none"; // 设置a标签不可见
 link.href = url; // 设置a标签的URL属性
 link.setAttribute("download", _that.filename); // 给a标签添加download属性并指定下载的文件名(记得加后缀指定下载的文件格式)

document.body.appendChild(link); // 将a标签节点添加在DOM中
 link.click(); // 触发a标签
 }
}
};
</script>

至此，小程序上传文件➡️后台存储 PDF 文件➡️后台管理系统下载存储的文件的整个流程已经走通😏，具体的业务需求就任君发挥了，比如将后台存储的所有文件名渲染在页面中，点击对应文件名将文件下载到本地、文件名多选再下载到本地等。

🎱案例 Github 地址：小程序中 PDF 文件的上传及下载

大风起兮云飞扬

xuezenghui6@gmail.com (Zander Hsueh) — Thu, 26 Sep 2019 10:00:31 +0800

2019.07.01—2021.05.21北京百星电子系统有限公司Front-end Developer

百星公司官网

📅开发周期：2019.07.04—2019.07.18

📄项目简介：公司官方网站。

🔗项目链接：Belstar（经过了多次迭代）

📐技术架构：Vue.js、Stylus

🔧相关工具：蓝湖、Sketch

🔒难点攻克：

页面小三角问题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


.arrow {
position: absolute;
top: 18px;
right: -47px;
width: 8px;
height: 8px;
border-top: 1px solid #e0e0e0;
border-right: 1px solid #e0e0e0;
transform: rotate(225deg);
}

📝项目总结：作为工作后第一个练手的项目，难度较小。完全的静态页面，暂时不需要连接后台获取数据，只是在细节上有几个点需注意：

Vue 组件的拆分要合理
git 上传代码的步骤要清晰

vue-router 滚动行为

1
2
3
4
5
6


// 文件位置： /router/index.js
export default new Router({
scrollBehavior (to, from, savedPosition) {
return { x: 0, y: 0 };
}
});

ePortal

📅开发周期：2019.07.22—2020.

📄项目简介：公司门户网站，采用 MEVN¹ 架构，将薪资系统、物流系统、项目管理系统、工单系统、生产管理系统等多个功能分支整合开发，是对公司内部管理的众多具体功能的实现。

🔗项目链接：ePortal

📐技术架构：Vue.js、Vuetify、Node.js、Express、MongoDB、Mongoose

🔧相关工具：Sketch、Robo 3T、Postman

🔒难点攻克：

📝项目总结：一次真正的锻炼机会。项目采用分组合作、模块分配至个人的开发方式，每个人既负责某模块的前端开发任务，同时也负责另一个模块的服务端开发工作。技术角度上基本是从零开始的——Node.js、Express、MongoDB，高效学习并应用于项目中，遇到问题也几乎都是自主解决。项目开发过程基本遵循 Git Flow 工作流，但开发前期在代码规范和复用方面做的并不好，后期在前辈的带领下对整个项目进行了..重构..，提升了总体的健壮性和规范性。目前仍处于持续的功能迭代阶段，ePortal 项目永不结案😄！

生产管理微信小程序

📅开发周期：2019.07.22—2019.12.25

📄项目简介：与 ePortal 项目的生产管理模块搭配使用并依托其进行上线，主要功能是用户根据其权限录入对应制作中心内打印机器的打印量，录入方式分为小程序内录入和扫描小程序码带参进入小程序录入页面录入，且可查看权限内制作中心里所有机器的录入历史记录。

🔗项目链接：微信内搜索小程序「工作量收集小助手」

📐技术架构：小程序开发语言、Node.js、Express、MongoDB、Mongoose

🔧相关工具：微信开发者工具

🔒难点攻克：

📝项目总结：起初与 ePortal 同步开发，由组内其它成员负责，后协助进行界面的完善及整体逻辑的修改优化。第一次接触小程序开发，在熟悉 Vue 语法的基础下摸清小程序的目录结构后进行得还是比较顺利的。唯一要提的就是微信小程序的官方文档写的真不咋地🤪，API 用法和参数描述得含糊不清让人走了不少弯路。

Bit POC

📅开发周期：2020.03.23—2020.04.30

📄项目简介：POC²类型项目，首要目的是验证使用 Bit 组件化管理前端代码的可行性。

🔗项目链接：无

📐技术架构：Bit、Vue.js、Linux

🔧相关工具：无

🔒难点攻克：

组件文档没有较好的管理方式，已尝试 bit.dev（不开源且费用不菲）、Storybook（不支持生产环境），皆不可行，最后采用的方案是 Typecho。

📝项目总结：初次接触 Bit，进行了系统地学习，撰写了 Bit 组件管理手册并完成相关的技术验证，相关内容见我的这篇博文。

委外设备管理系统

📅开发周期：2020.05.12—2020.11.12

📄项目简介：依旧是 ePortal 工程的功能迭代，要问为什么伶出来，其一，该项目与多个第三方平台对接，如钉钉、GitLab、微信小程序；其二，也是项目周期跨度如此大的原因——组织变更，中期由我接手负责该项目的管理工作。当然，最终顺利部署上线。

🔗项目链接：ePortal-生产管理

📐技术架构：Vue.js、Vuetify、Node.js、Express、MongoDB、Mongoose

🔧相关工具：Flexmonster、MongoDB Compass、Trello

🔒难点攻克：

aggregate 大数据量大、多管道操作情景下的接口优化

业务中遇到了聚合管道操作 30w 条数据的情况，导致接口频繁超时，先使用 MongoDB Compass 分析管道操作耗时，从管道操作顺序优化、集合索引优化、业务查询方式优化等多角度入手，配合服务端定时任务完成 API 请求耗时由 >10s 到 <50ms 的转变。

📝项目总结：事实证明 Team Leader 和 Project Manager 不是多么容易当的，尤其考虑所在环境，项目期间基本是被当开发、设计、产品经理、项目经理、测试、运维都使了一遍。如果要总结这个项目学到了什么，那我一定会忘记繁杂的业务、抛弃使用得驾轻就熟的 aggregate 而选择“管理”和“沟通”，完备合理的项目管理能使团队达到 1+1>2 的效果，而做好协调沟通工作也并非易事，仅此一役，受益匪浅。

企业报价系统

📅开发周期：2020.11.18—2021.02.20

📄项目简介：用于企业内部销售部门进行公司产品服务的业务报价，规划灵活易扩展的价格结构及价格维护方式，多种报价模式下导出报价单，审批流程接入钉钉 API。Domain Service 架构，前端集成于 ePortal，后端服务切分、领域驱动，采用 Nest.js + GraphQL 架构。

🔗项目链接：无

📐技术架构：

客户端：Vue.js、Vuetify、Apollo-Client
服务端：Node.js、Nest.js、TypeScript、Apollo-Server、Mongoose
数据库：MongoDB

🔧相关工具：Trello

🔒难点攻克：

📝项目总结：

2021.05.31—2021.09.21北京韦尔科技有限公司Front-end Developer 2021.10.06—至今Costco Wholesale ChinaSoftware Developer

Architecture Optimization & DevOps

📅开发周期：2020.10.15—2021.01.05

📄项目简介：

🔗项目链接：无

📐技术架构：

🔧相关工具：

🔒难点攻克：

📝项目总结：

MongoDB + Express + Vue.js + Node.js 技术架构体系。 ↩︎
Proof of concept，概念验证，对一个想法、一种技术的不完整实现，以证明其可行性。 ↩︎