天天基金网 NodeJS 版 API - 文档与部署（二）

kouchao
280 阅读3分钟

我报名参加金石计划1期挑战——瓜分10万奖池，这是我的第2篇文章，点击查看活动详情

内容这可能对新手更友好，过程很枯燥，可以直接看总结

最开始文档使用的 docsify 搭建，它只需要一个简单的 html，通过 js 解析 md 文件，但是他不满足对于 seo 的优化，由于是运行时打开速度也会慢一些，后面改用 vuepress。

基本思路

文档提交到 github，使用 actions 部署 github pages

github pages

github pages 是由 github 提供的静态网站托管服务，开源项目是免费的。设置步骤可以 google 一下，这里不是保姆教程，提供思路与方法，实验还是交给读者。

actions

actions 是由 github 提供的工作流，用于自动化检查，测试，构建，部署等，可以做很多事情。

部署文档

当代码提交到 main 分支，docs 目录发生变化时，编译文档，放到 github pages 所需的分支 gh-pages。

文档部分

首页

新建 docs 目录，用于存放文档文件。README.MD 作为主页，以下部分代码。 vuepress 以这种 YAML 方式来组织首页的布局，已经 seo 相关的设置。

---
home: true
title: 天天基金网 API
heroText: 天天基金网 API
tagline: 天天基金网 NodeJS 版 API
actions:
  - text: 快速开始
    link: /guide
    type: primary
  - text: Api 列表
    link: /apis
    type: secondary
features:
  - title: 持续更新
    details: 接口数据将持续更新
  - title: 提高字段可读性
    details: 在接口完成度较高的情况下，会考虑整体的字段可读性
  - title: 文档完善
    details: 不断完善文档，不管是使用、贡献、学习都能清楚的看懂
  - title: 测试用例
    details: 提高覆盖率，以保证每个接口可用
  - title: docker 部署
    details: 在 docker 中部署，使用起来更方便
  - title: vercel 示例
    details: 使用 vercel 提供线上 api
footer: Copyright © 2022-present kouchao
---

配置

.vuepress/config.js 用来对 vuepress 配置，所有的配置都在这个文件中。

import { defaultTheme } from 'vuepress'
export default {
  base: '/TiantianFundApi/',
  theme: defaultTheme({
    navbar: [
      {
        text: '首页',
        link: '/',
      },
      {
        text: '指南',
        link: '/guide',
      },
      {
        text: 'Api 列表',
        link: '/apis',
      },
      {
        text: 'Github',
        link: 'https://github.com/kouchao/TiantianFundApi',
      },
    ],
  }),
}

actions 部分

时机

main 分支 push，docs 目录有修改。其他文件更新不需要重新执行文档的部署，做一下限制减少部署操作。

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'

环境

node 环境，包管理使用 pnpm。这里做了一个优化，使用 pnpm-lock.yaml 做缓存，如果 pnpm-lock.yaml 没有更改，则 node_modules 会继续使用，否则才重新安装依赖，这样就可以节省一段时间。

- name: Setup Node.js
  uses: actions/setup-node@v3
  with:
    node-version: 16
    cache: 'pnpm'
    
- name: Install dependencies
  run: pnpm i --frozen-lockfile

编译

准备好环境后，就可以像本地开发一样执行想要的操作，vuepress 是需要编译的，在自动化的过程执行编译

 - name: Build VuePress site
  run: pnpm docs:build

部署

上述步骤将文档编译到 docs/.vuepress/dist，只需要将编译后的文件放到 gh-pages 就可以，使用了 crazy-max/ghaction-github-pages@v2，可以方便的做这个操作。通常情况下可以使用别人封装的 action来减少工作。顺带提一下 secrets.GITHUB_TOKEN，为了防止自己的一些密码账号之类的关键信息被看到，在 ci 中使用 ${{ secrets.GITHUB_TOKEN }} 可以取到仓库在设置中填写的一些信息。

  - name: Deploy to GitHub Pages
    uses: crazy-max/ghaction-github-pages@v2
    with:
      target_branch: gh-pages
      build_dir: docs/.vuepress/dist
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

总结

主要学习一下处理问题的思路。

  1. 文档的搭建。
  2. github pages 的使用。
  3. 做一些缓存优化，减少不必要的操作，同时让执行更快。
  4. 使用一些成型的工具，减少工作量。
  5. 时刻注意安全问题。
  6. 让代码自动起来。

TiantianFundApi（🙏🏻 求大家点赞、收藏、star ~）

系列

avatar
文章
阅读
粉丝