在2023年9月19日，Go发布的1.22版本，修复了循环变量作用域的问题，最近在用其他语言写代码时，也遇到了类似的问题。于是意识到不同的编程语言对这种情况的处理有所不同，便有了这篇文章。

Go

首先回顾一下Go语言的循环变量问题，考虑下面的简单代码，生成多个打印数字的函数，然后调用这些函数。

package main
import "fmt"
var funcs []func()

func main() {
    for i := 0; i < 3; i++ {
        funcs = append(funcs, func() {
            fmt.Println(i)
        })
    }
    for _, f := range funcs {
        f()
    }
}

预期输出为

0
1
2

但实际输出为

3
3
3

见多识广的你可能已经猜到了：首先Go语言中循环变量在每次循环时会重复使用（当然，从1.22开始，每次迭代都有自己单独的循环变量），而不是重新创建一个新的变量。其次上述示例中的闭包函数以引用的方式捕获了变量¹（实际上是使用指针实现的）。这些因素共同造成了上述的输出不符合预期。

那么如何修复呢？只需要添加一个局部变量即可。

for i := 0; i < 3; i++ {
    i := i // 给一个局部变量赋值
    funcs = append(funcs, func() {
        fmt.Println(i)
    })
}

或者通过闭包保持循环变量的值，本质上都是一样的。

for i := 0; i < 3; i++ {
    // 定义闭包函数
    var make_func = func(x int) func() {
        var func1 = func() {
            fmt.Println(x)
        }
        return func1
    }
    funcs = append(funcs, make_func(i))
}

看上去不太优雅，不过从1.22开始，不需要这些额外的操作了。

JavaScript

看一看JavaScript中的情况。编写一个类似的代码。

const funcs = []
for (let i = 0; i < 3; i++) {
    funcs.push(() => console.log(i))
}
for (const f of funcs) {
    f()
}

执行后你会发现输出为

0
1
2

这是因为JavaScript的for中使用let或const声明的变量是语句的局部变量，属于其块级作用域，于是表现上和Go 1.22一致了，自然也就没有最开始循环变量的问题了。但是，如果你使用了古老的var，那么情况就和Go 1.22之前一样了²³

Python

那么Python的情况呢，首先我们要知道，Python中只有模块（module），类（class）以及函数（def、lambda）才会引入新的作用域，其他代码块（如if、for、while）都不会引入新的作用域。同时，Python中的闭包是以引用的方式捕获变量的，所以我们已经可以猜到最终输出是相同值了。

funcs = []
for i in range(3):
    funcs.append(lambda: print(i))
for f in funcs:
    f()

输出为

2
2
2

由于for不创建块级作用域，创建局部变量的方法失效了，但我们仍然可以用闭包的方法解决这个问题。

funcs = []
for i in range(3):
    funcs.append((lambda x: lambda: print(x))(i))
    # 或者使用默认参数
    # funcs.append(lambda i=i: print(i))
for f in funcs:
    f()

C++

C++的循环变量是重复使用的，但是C++的情况有些特殊，因为C++允许开发人员指定lambda使用值捕获还是引用捕获⁴。既然允许使用值捕获，那么自然不存在上述循环变量的问题了。

#include<functional>
#include<iostream>
#include<vector>
std::vector<std::function<void()>> fList;
int main() {
    for (int i = 0; i < 3; i++) {
        fList.push_back([i]() { 
            std::cout << "i = " << i << std::endl;
        });
    }
    for (auto f: fList) {
        f();
    }
}

执行后输出为

i = 0
i = 1
i = 2

注意你不能把lambda函数中的值捕获[i](){...}直接改为引用捕获[&i](){...}，这会导致悬垂引用，因为i在循环结束后就被销毁了。

总结

本文对4种语言循环变量的表现进行了解释，但是并没有深入讨论，如果深入，就需要考虑编译器和汇编层面的东西。如果对底层实现感兴趣，可以深入研究一下不同语言闭包捕获变量的机制。对于开发来说，注意循环变量的作用域，以及闭包的捕获方式，可以避免一些不必要的错误，这就足够了。

过年之前小水一篇，以示我还活着…… 😂

准备工作

首先我们需要为 Astro 安装 react 和 tailwindcss 扩展：

npm install -D @astrojs/react @astrojs/tailwindcss

扩展的配置请参考官方教程，此处省略了。

然后我们需要将 tailwindcss 的黑暗模式切换方式更改为 class 模式，即通过在 html 标签上添加 .dark 类来开启暗黑模式。在 tailwind.config.ts 中添加如下配置：

import type { Config } from 'tailwindcss'
export default {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  darkMode: 'class',
  // ...
} satisfies Config;

颜色模式的切换逻辑

为了让用户有自由选择权，我们需要提供三个选项：自动、浅色、深色。自动选项将根据用户操作系统的颜色模式自动切换，而浅色和深色选项则是固定的。我们将使用 localStorage 来缓存用户的选择，以便在下次用户访问网站时恢复用户的偏好。

一个基础的颜色模式切换逻辑如下：

在进入不同颜色模式的时候需要更改 html 标签上的 .dark 类和 localStorage 中的 theme 值。我们可以写出颜色模式切换的函数：

function switchColorMode(colorMode: 'light' | 'dark' | 'auto') {
  if (colorMode === 'dark') {
    document.documentElement.classList.add('dark');
    document.documentElement.style.colorScheme = 'dark';
    localStorage.setItem('theme', 'dark');
  } else if (colorMode === 'light') {
    document.documentElement.classList.remove('dark');
    document.documentElement.style.colorScheme = 'light';
    localStorage.setItem('theme', 'light');
  } else if (colorMode === 'auto') {
    const isMatchDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    if (isMatchDark) {
      document.documentElement.classList.add('dark');
      document.documentElement.style.colorScheme = 'dark';
    } else {
      document.documentElement.classList.remove('dark');
      document.documentElement.style.colorScheme = 'light';
    }
    localStorage.setItem('theme', 'auto');
  }
}

和初始化颜色模式的函数：

function initColorMode() {
  const storedTheme = JSON.parse(window.localStorage.getItem('theme') ?? '"auto"');
  let presetTheme;
  if (storedTheme === 'auto') {
    presetTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
  } else {
    presetTheme = storedTheme;
  }
  if (presetTheme === 'dark') {
    document.documentElement.classList.add('dark');
    document.documentElement.style.colorScheme = 'dark';
  } else {
    document.documentElement.classList.remove('dark');
    document.documentElement.style.colorScheme = 'light';
  }
}

OK，到目前为止，我们写好了初始化和用于切换的工具函数，但是用户选择和OS颜色模式变更时如何触发switchColorMode呢？对于用户选择，处理逻辑与 UI 框架相关；对于 OS 变更，显然要监听 prefers-color-scheme 媒体查询的变化了。这写会在后面给出，接下来我们要考虑 React 框架上的实现了。

包装为 Hook

在React中，对于与处理 UI 无关的逻辑，我们可以将其包装为一个 React Hook，以便在组件中使用。上面提到了 localStorage 和媒体查询，这两个都可以包装为 Hook，我们可以自己写，也可以用现成的实现，例如 useLocalStorage 和 useMediaQuery。

那么假设这两个 Hook 已经有了，现在我们可以写出颜色模式切换的 Hook：

import useLocalStorage from './useLocalStorage';
import useMediaQuery from './useMediaQuery';
import { useEffect } from 'react';

export type Theme = 'light' | 'dark' | 'auto';

export default function useTheme(defaultTheme: Theme = 'auto') {
  const isMatchDark = useMediaQuery('(prefers-color-scheme: dark)');
  const [value, setValue, remove] = useLocalStorage<Theme>('theme', defaultTheme);
  const [theme, setTheme] = useState<Theme>(value);

  const colorMode = theme === 'auto' ? (
    value === 'auto' ? (isMatchDark ? 'dark' : 'light') : value
  ) : theme;
  useEffect(() => {
    if (value && value !== theme) {
      setTheme(value);
    }
  }, [])

  useEffect(() => {
    if (colorMode === 'dark') {
      document.documentElement.classList.add('dark');
      document.documentElement.style.colorScheme = 'dark';
    }
    if (colorMode === 'light') {
      document.documentElement.classList.remove('dark');
      document.documentElement.style.colorScheme = 'light';
    }
  }, [colorMode]);

  const setThemeAndStorage = (theme: Theme) => {
    setValue(theme);
    setTheme(theme);
  }

  return {
    colorMode: colorMode, // light or dark
    theme: theme, // auto or light or dark
    setTheme: setThemeAndStorage, // set theme and save to localStorage
  }
}

用法是：

const { colorMode, theme, setTheme } = useTheme();

setTheme参数中我们的给用户提供了三种选择，思路是维持用户的选择直到用户重新选择颜色模式，而不是在系统切换颜色模式时放弃用户的设定。

编写 React 组件

我们来编写一个最朴素的组件，不附加任何样式。

import useTheme, { type Theme } from '@/hooks/useTheme';

function ThemeToggle() {
  const { colorMode, theme, setTheme } = useTheme();
  const [isMounted, setIsMounted] = useState(false);

  useEffect(() => {
    setIsMounted(true);
  }, []);
  if (!isMounted) {
    return null;
  }

  const handleChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
    setTheme(e.target.value as Theme);
  }
  return (
    <select value={theme} onChange={handleChange}>
      <option value="auto">自动</option>
      <option value="light">浅色</option>
      <option value="dark">深色</option>
    </select>
  )
}

export default ThemeToggle;

注意这里在组件挂载后才显示，这是为了避免组件在客户端和服务器渲染时不一致的问题，尤其是当你需要根据不同颜色模式显示不同的内容时。

解决 FOUC 问题

FOUC（Flash of Unstyled Content）是指在页面加载完成前，页面上的内容没有样式，页面加载完成后，样式突然变化的现象。这是因为我们与颜色模式相关的 JS 的加载执行 晚于 html 首次渲染，浏览器提前因此我们需要在页面加载完成前将颜色模式初始化。

Astro 提供了 is:inline 指令，允许我们为页面保留 script 和 style 标签不被移除。为了及时初始化颜色模式，我们需要在 head 标签中添加如下代码（即上述初始化代码）：

<script is:inline>
  (function() {
    const storedTheme = JSON.parse(window.localStorage.getItem('theme') ?? '"auto"');
    let presetTheme;
    if (storedTheme === 'auto') {
      presetTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
    } else {
      presetTheme = storedTheme;
    }
    if (presetTheme === 'dark') {
      document.documentElement.classList.add('dark');
      document.documentElement.style.colorScheme = 'dark';
    } else {
      document.documentElement.classList.remove('dark');
      document.documentElement.style.colorScheme = 'light';
    }
  })()
</script>

最好将这段代码置于 head 标签尽量靠前的位置，以便浏览器尽早执行。

最后我们还需要支持 Astro 的 ViewTransition 功能，否则会出现同 FOUC 一样的闪烁问题，由于 Astro 不会在页面切换时重新执行内联脚本（参考官方文档），我们在页面的 astro 代码中添加：

<script>
  // prevent flash when using view transitions in astro
  const initColorMode = () => {
    const storedTheme = JSON.parse(window.localStorage.getItem('theme') ?? '"auto"');
    let presetTheme;
    if (storedTheme === 'auto') {
      presetTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
    } else {
      presetTheme = storedTheme;
    }
    if (presetTheme === 'dark') {
      document.documentElement.classList.add('dark');
      document.documentElement.style.colorScheme = 'dark';
    } else {
      document.documentElement.classList.remove('dark');
      document.documentElement.style.colorScheme = 'light';
    }
  };

  // Runs on initial navigation
  initColorMode();
  // Runs on view transitions navigation
  document.addEventListener('astro:after-swap', initColorMode);
</script>

注意这个script标签没有is:inline指令，并且执行的时机是事件astro:after-swap，关于 ViewTransition 的生命周期，你可能会关心 这个PR。

至此我们就完成了 Astro 的暗黑模式支持，最后如果你要编写黑暗模式的样式，记得在选择器前加上 .dark 类，或者直接使用 Tailwind CSS 的 dark: 前缀。]]> https://suborbit.net/posts/build-my-pc-in-2023 https://suborbit.net/posts/build-my-pc-in-2023 Thu, 28 Sep 2023 00:00:00 GMT =4年即可； 基本结论：这台主机不会用太久，所以配置不求最新，能省则省。 明确需求 性能需求：日常文档处理、浏览网页、音乐、视频、基本游戏需求需要满足，不常玩3A大作；有跑ai模型的学习需求…]]> 开个玩笑~

事情的缘由是，最近笔记本坏了，鉴于手里已经有一台 Surface 了，所以考虑组装一个台式机，作为小白，人生第一次完整装机，记录一下过程。

预算

• 预算：7000~9000元，不包括显示器、键鼠、耳机；
• 生命周期：>=4年即可；

基本结论：这台主机不会用太久，所以配置不求最新，能省则省。

明确需求

• 性能需求：日常文档处理、浏览网页、音乐、视频、基本游戏需求需要满足，不常玩3A大作；有跑ai模型的学习需求，常用开发工具不能出现卡顿；
• 稳定性需求：要求低故障率，不会爆炸；
• 外观需求：风格一致即可，不需要RGB灯光，无颜色偏好；

基本结论：关键配件选择一线品牌，非关键配件尽量高性价比，按照 无光黑色 风格搭配即可。

型号调研

需要购置的配件有：CPU、主板、内存、硬盘、显卡、机箱、电源、散热器、风扇；

CPU

身为程序员，果然还是更倾向于Intel。关于Intel CPU的详细命名规则，在英特尔官网有写：英特尔® 处理器名称和编号。对于桌面端消费级CPU，知道13600中13代表“代数”，600代表子型号（SKU），F后缀代表无核显，K后缀不锁倍频就够了。

目前最新一代CPU为2022年10月发布的13代，一般SKU越大性能越好。由于不求新，就同时比较12代和13代，但是我需要核显。热门的几款型号分别是：

i5 13400、i5 13490、i5 12600(k)、i5 12700(k)、i5 13600(k)、i5 13700(k)

它们的性能依次递增，价格也一样。其中我最关注的是12600(k)和13600(k)，看了参数和评测，发现13600除了核心频率提高了之外，相比12600主要是增加了4给小核，以及缓存变大了很多。还有一点需要提到的是，市面上有一种称为“散片”的CPU，没有正规包装，但是价格会便宜一点。

思考了很久，感觉这台主机不会用太长时间，所以最终选择了12600k，性能足够，价格更便宜。选择带k的CPU是因为，非k后缀的CPU锁SA电压，内存在Gear1模式下很难超过3200mhz的频率。

主板

不玩超频，倾向matx版型，可供选择的芯片组有b660、b760这两代。b760相比b660主要是增加了PCIe4.0接口的数量。需要注意不同ddr代数的主板不能混用，内存条接口都不一样。

为了贯彻能省则省的原则，直接考虑12代板U。本人暂时不认为现阶段ddr4和ddr5内存在工作的体验上有质的飞跃，所以主板就选了微星的b660m mortar ddr4 wifi，这样就可以省下一点钱。不过这款主板有个max版本，可以超外频，只需要加50RMB，后来就换了这个尝鲜。

内存

需要匹配主板的ddr4内存条，不要灯光，不超频，市面上可选产品很多，考虑到本人经常同时开很多网页和软件，最终选择的宏碁凌霜 3600 C18 16G *2。

硬盘

宏碁GM7 4TB只需要999！长存颗粒，看着是真香。不过我最终选择了另外一个，宏碁GM7000 2TB，这个带2G的DRAM缓存，京东价格599。

显卡

预算有限，不能上4080、4090这样的高端显卡了，我决定买一个显存大一点的，好能跑得动一些吃显存的模型。但是找来找去，只有RTX 4060ti 16G这种答辩，在显存频率没有太大提升的情况下，显存位宽砍半，仅有128bit，导致显存带宽大打折扣，便宜一点的和贵一点的显卡都没有大显存，二手3090怕矿卡不敢买，无奈呀。

最后买了影驰金属大师RTX 4060ti 16G MAX OC，性价比不是很高，不过是跟无光黑色机箱倒是挺搭的。

机箱

海景房就算了，过一年还要搬家，怕碎，其他能装matx主板就行。于是跟风！选了乔思伯松果D31 mesh板。

散热器

跟风！酷里奥P60T 性能版 纯黑色，双塔风冷散热器。听说噪声小、性能很棒。

风扇

随便选了利民G12*3+利民S12，后者带一圈灯环，还是有一点点灯光的。实际上风扇是我最后买的，在此之前其他配件都到齐了，我发现即使只装一个风冷也能完美使用，所以风扇就没配全。

PS: 这套风扇真是一言难尽，静音确实是静音，但是没多少风量，早知道不如买更便宜的C12C。

电源

可选项很多，网上关于谁好谁坏的争论也很多，综合考虑下，我买了利民TG650 650w金牌全模组，五年质保，主要是价格便宜（汗）。

配置总结

发现拼多多上某些硬件好便宜，遂从拼多多入手大多数配件，最终配置单如下。

配件	型号	渠道	入手价（元）
CPU	Intel Core i5 12600k 散片	拼多多	1405
主板	微星 b660m mortar max wifi ddr4	拼多多	917
内存	宏碁掠夺者凌霜 3600 C18 16G *2	拼多多	454
硬盘	宏碁掠夺者 GM7000 2TB	拼多多	593
显卡	影驰 RTX4060ti 金属大师 16G MAX OC	淘宝	3689
散热器	酷里奥 P60T 性能版 黑色	拼多多	247
机箱	乔思伯松果 D31 黑色 mesh版	拼多多	195
风扇	利民 G12 *3 + 利民 S12 黑色 *1	拼多多	86
电源	利民TG650 650w金牌全模组	京东	316
总计			7902

这其中不少配件还能再缩水，恐怕还能挤出几百块来😂。

成品展示

参照b站教程： 【装机教程】全网最好的装机教程，没有之一

繁琐的过程就省略了，展示一下成果吧。

主打一个硬朗风格。装好后，CPU和内存我都尝试了超频，不得不说，超不了多少，体质是真一般，不过无所谓了。Enjoying~

后记

2023.10.3 淦，4060ti 16g 最低价被干到了3099，亏麻了。

2023.10.6 SSD涨了200块，我貌似刚好赶在涨价钱入的手。]]> https://suborbit.net/posts/extend-markdown-syntax-practical https://suborbit.net/posts/extend-markdown-syntax-practical Mon, 07 Aug 2023 00:00:00 GMT

function exitMyNodeType(token) {
  const node = this.stack[this.stack.length - 1] as MyNodeType;
  this.exit(token);
  // previous code will case error
  // const node = this.exit(token) as MyNodeType;
}

上一篇文章 讲了 Remark 扩展新语法的方法，现在我们就来实践吧。

在这篇文章里，我们将会实现两个有趣的新语法，分别是：

• Spoiler（黑幕）：形成对文字的遮挡效果，只有在鼠标悬停时才会显示。
• Admonition（警告框）：使用块级元素来强调一段文字，可以有不同的类型、颜色和图标。

Spoiler

语法定义

先来介绍一下 Spoiler 的语法。使用 !! 双叹号包裹行内文本，文本将会具有 Spolier 效果。

!!这是一条 Spoiler 测试文本。这是一条 Spoiler 测试文本。!!

效果如下（鼠标悬停在文本上，以显示文字）：这是一条 Spoiler 测试文本。这是一条 Spoiler 测试文本。

文件结构

- remarkSpoiler
  - syntax.ts       // micromark 扩展
  - fromMarkdown.ts // mdast-util-from-markdown 扩展
  - index.ts        // 插件入口

micromark 扩展

import { markdownLineEnding } from 'micromark-util-character';
import { factorySpace } from 'micromark-factory-space';
import { codes, types, constants } from 'micromark-util-symbol';
import type { Construct, Tokenizer, State, Extension as MicromarkExtension } from 'micromark-util-types';

// 定义 spoiler Tokenizer
const tokenizeSpoiler: Tokenizer = function(effects, ok, nok) {
  const self = this;
  const start: State = function(code) {
    effects.enter('spoiler');
    return effects.attempt(
      marker,
      factorySpace(effects, contentStart, types.whitespace),
      nok
    )
  }
  const contentStart: State = function(code) {
    effects.enter(types.chunkText, {
      contentType: constants.contentTypeText,
    })
    return content;
  }
  const content: State = function(code) {
    return effects.check(
      marker,
      factorySpace(effects, contentAfter, types.whitespace),
      comsumeData
    )
  }
  const comsumeData: State = function(code) {
    if (markdownLineEnding(code) || code === codes.eof) {
      return nok;
    }
    effects.consume(code);
    return content;
  }
  const contentAfter: State = function(code) {
    effects.exit(types.chunkText);
    return effects.attempt(marker, after, nok);
  }
  const after: State = function(code) {
    effects.exit('spoiler');
    return ok;
  }
  return start;
}

// 定义分界符 (!!) 的 Tokenizer
const tokenizeMarker: Tokenizer = function(effects, ok, nok) {
  let markerSize = 0;
  if (this.previous === codes.exclamationMark) {
    return nok;
  }
  const start: State = function(code) {
    effects.enter('spoilerMarker');
    return marker;
  }
  const marker: State = function(code) {
    if (code === codes.exclamationMark) {
      effects.consume(code);
      markerSize++;
      return marker;
    }
    if (markerSize == 2) {
      effects.exit('spoilerMarker');
      markerSize = 0;
      return ok;
    }
    return nok;
  }
  return factorySpace(effects, start, types.whitespace);
}

const marker: Construct = {
  tokenize: tokenizeMarker,
  partial: true
}

const spoiler: Construct = {
  name: 'spoiler',
  tokenize: tokenizeSpoiler
}

export const syntax = (): MicromarkExtension => {
  return {
    text: {
      [codes.exclamationMark]: spoiler,
    }
  }
}

mdast-util-from-markdown 扩展

在 html 上实现spoiler效果比较简易，只需要添加一些 css 即可。

import type { Parent } from 'mdast';
import type { Handle, Extension as FromMarkdownExtension } from 'mdast-util-from-markdown';

// 定义 spoiler 节点类型
export interface Spoiler extends Parent {
  type: 'spoiler',
};

// 声明自定义 mdast 类型
declare module 'mdast' {
  interface StaticPhrasingContentMap {
    spoiler: Spoiler;
  }
}

export const fromMarkdown = (): FromMarkdownExtension => {
  const enterSpoiler: Handle = function(token) {
    this.enter<Spoiler>({
      type: 'spoiler',
      children: [],
    }, token);
  }
  const exitSpoiler: Handle = function(token) {
    const node = this.exit(token) as Spoiler;
    node.data = {
      ...node.data,
      hName: 'span',
      hProperties: {
        className: 'bg-current hover:bg-transparent',
      },
    }
  }
  return {
    enter: {
      spoiler: enterSpoiler,
    },
    exit: {
      spoiler: exitSpoiler,
    }
  }
}

完善插件

这里编写了一个 add 工具函数，用来向对象中某列表属性添加元素，如果属性不存在则创建一个新的列表。

import type { Plugin } from 'unified';
import type { Root } from 'mdast';
import { syntax } from './syntax';
import { fromMarkdown } from './fromMarkdown';

const remarkSpoiler: Plugin<[], Root> = function() {
  const data = this.data();
  function add(key: string, value: unknown) {
    if (Array.isArray(data[key])) {
      (data[key] as unknown[]).push(value);
    } else {
      data[key] = [value];
    }
  }
  add('micromarkExtensions', syntax());
  add('fromMarkdownExtensions', fromMarkdown());
}
export default remarkSpoiler;

Admonition

语法定义

使用三个叹号作为前缀，后面紧随 admonition 的类型，类型之后可以跟一个可选的标题，标题和类型之间用空格分隔。

从第二行开始为 admonition 的内容，需要有 4 个空格的缩进。如果下一行的内容仍然以 4 个空格缩进，则该内容块仍然属于 admonition，直到遇到非法缩进。

!!! info 注意
    这是一条注意事项。
    !!! tip 提示：_标题可以带有格式_
        Admonition 可以嵌套使用。

文件结构

- remarkAdmonition
  - syntax.ts       // micromark 扩展
  - fromMarkdown.ts // mdast-util-from-markdown 扩展
  - index.ts        // 插件入口
  - styles.css      // 附加样式

micromark 扩展

import { asciiAlpha, asciiAlphanumeric, markdownLineEnding, markdownSpace } from 'micromark-util-character';
import { factorySpace } from 'micromark-factory-space';
import { codes, types, constants } from 'micromark-util-symbol';
import type { TokenizeContext, Construct, Tokenizer, Effects, Exiter, State, Token, Extension as MicromarkExtension } from 'micromark-util-types';

// characters in name can be: a-z, A-Z, 0-9, -, _
// but the first character must be a-z or A-Z
function factoryName(
  this: TokenizeContext, 
  effects: Effects, 
  ok: State, 
  nok: State, 
  type: string
) {
  const self = this;
  const start: State = function(code) {
    if (asciiAlpha(code)) {
      effects.enter(type);
      effects.consume(code);
      return name;
    }
    return nok;
  }

  const name: State = function(code) {
    if (
      code === codes.dash ||
      code === codes.underscore ||
      asciiAlphanumeric(code)
    ) {
      effects.consume(code);
      return name;
    }
    effects.exit(type);
    return self.previous === codes.dash || self.previous === codes.underscore
      ? nok
      : ok;
  }
  return start;
}
// tokenizing title, the title can be any character except line ending
function factoryTitle(
  effects: Effects,
  ok: State,
  nok: State,
  type: string,
) {
  let previous: Token;
  const start: State = function(code) {
    effects.enter(type);
    return titleStart;
  }
  const titleStart: State = function(code) {
    if (markdownLineEnding(code) || code === codes.eof) {
      effects.exit(type);
      return ok;
    }
    const token = effects.enter(types.chunkText, {
      contentType: constants.contentTypeText,
      previous
    })
    if (previous) previous.next = token
    previous = token

    effects.consume(code);
    return title;
  }
  const title: State = function(code) {
    if (markdownLineEnding(code) || code === codes.eof) {
      effects.exit(types.chunkText);
      effects.exit(type);
      return ok;
    }
    effects.consume(code);
    return title;
  }
  return start;
}

const tokenizeIndent: Tokenizer = function(effects, ok, nok) {
  const self = this;
  const prefix: State = function(code) {
    if (!self.containerState) {
      throw new Error('expected state')
    }
    if (typeof self.containerState.indent !== 'number') {
      throw new Error('expected indent')
    }
    return factorySpace(
      effects,
      afterPrefix,
      'admonitionIndent',
      constants.tabSize + 1,
    )
  }

  const afterPrefix: State = function(code) {
    if (!self.containerState) {
      throw new Error('expected state')
    }
    const tail = self.events[self.events.length - 1]
    if (tail) {
      const [type, token, context] = tail;
      if (token.type === 'admonitionIndent'
        && token.end.column - 1 === self.containerState.indent) {
        return ok;
      }
    }
    return nok;
  }
  return prefix
}

const tokenizeBlankLine: Tokenizer = function(effects, ok, nok) {
  const self = this;
  const start: State = function(code) {
    return markdownSpace(code)
      ? factorySpace(effects, after, types.whitespace)
      : after
  }
  const after: State = function(code) {
    return code === codes.eof || markdownLineEnding(code) ? ok : nok
  }
  return start
}

const tokenizeAdmonitionStart: Tokenizer = function(effects, ok, nok) {
  // used for factoryName
  const self = this;
  // define data
  let markerSize = 0;
  const tail = self.events[self.events.length - 1];
  let initialIndent = 0;
  if (tail) {
    const [tailType, tailToken, tailContext] = tail;
    initialIndent = tailToken.type === 'admonitionIndent'
      ? tailContext.sliceSerialize(tailToken, true).length
      : 0;
  }
  if (!self.containerState) {
    throw new Error('expected state')
  }
  self.containerState.indent = initialIndent + constants.tabSize;
  // define states
  const start: State = function(code) {
    effects.enter('admonition');
    effects.enter('admonitionPrefix');
    if (code === codes.exclamationMark) {
      effects.enter('admonitionMarker');
      return marker;
    }
    return nok;
  }
  const marker: State = function(code) {
    if (code === codes.exclamationMark) {
      effects.consume(code);
      markerSize++;
      return marker;
    }
    if (markerSize !== 3) {
      return nok;
    }
    effects.exit('admonitionMarker');
    return afterMarker;
  }
  const afterMarker: State = function(code) {
    if (markdownSpace(code)) {
      return factorySpace(effects, afterMarker, types.whitespace);
    }
    return name;
  }
  const name: State = function(code) {
    return factoryName.call(self, effects, afterName, nok, 'admonitionName');
  }
  const afterName: State = function(code) {
    if (markdownSpace(code)) {
      return factorySpace(effects, afterName, types.whitespace);
    }
    if (markdownLineEnding(code) || code === codes.eof) {
      return after;
    }
    return title;
  }
  const title: State = function(code) {
    return factoryTitle(effects, afterTitle, nok, 'admonitionTitle');
  }
  const afterTitle: State = function(code) {
    if (!markdownLineEnding(code)) {
      effects.consume(code);
      // self.parser.lazy[t.start.line] = false
      return afterTitle;
    }
    return after;
  }
  const after: State = function(code) {
    effects.exit('admonitionPrefix');
    return ok;
  }
  return start;
}

const tokenizeAdmonitionContinuation: Tokenizer = function(effects, ok, nok) {
  return effects.check(blankLine, ok, effects.attempt(indent, ok, nok))
}

const exit: Exiter = function(effects) {
  effects.exit('admonition');
}

const indent: Construct = {tokenize: tokenizeIndent, partial: true}
const blankLine: Construct = {tokenize: tokenizeBlankLine, partial: true}
const admonition: Construct = {
  name: 'admonition',
  tokenize: tokenizeAdmonitionStart,
  continuation: {
    tokenize: tokenizeAdmonitionContinuation,
  },
  exit: exit,
}

export const syntax = (): MicromarkExtension => {
  return {
    document: {
      [codes.exclamationMark]: admonition,
    }
  }
}

mdast-util-from-markdown 扩展

import type { Paragraph, Parent, Text, Content } from 'mdast';
import type { Content as HastContent } from 'hast';
import type { Handle, Extension as FromMarkdownExtension } from 'mdast-util-from-markdown';
import { fromHtml } from 'hast-util-from-html';

export interface Admonition extends Parent {
  type: 'admonition',
  name: string,
};
export interface admonitionHTML extends Parent {
  type: 'admonitionHTML',
}
declare module 'mdast' {
  interface BlockContentMap {
    admonitionHTML: admonitionHTML;
    admonition: Admonition;
  }
  interface ParagraphData {
    admonitionTitle?: boolean;
  }
}

const admonitionConfig: Record<string, {
  title: string,
  icon: string,
  class: string,
}> = {
  note: {
    title: '备注',
    icon: '<svg>...</svg>',
    class: 'admonition-note',
  },
  info: {
    title: '信息',
    icon: '...',
    class: 'admonition-info',
  },
  tip: {
    title: '提示',
    icon: '...',
    class: 'admonition-tip',
  },
  caution: {
    title: '注意',
    icon: '...',
    class: 'admonition-caution',
  },
  danger: {
    title: '危险',
    icon: '...',
    class: 'admonition-danger',
  },
}

function h (
  tagName: string,
  properties: Record<string, any>,
  children?: (Content | undefined | null | false)[],
): admonitionHTML {
  const filteredChildren = children?.filter<Content>((child): child is Content => {
    return child !== undefined && child !== null && child !== false;
  }) ?? [];
  return {
    type: 'admonitionHTML',
    data: {
      hName: tagName,
      hProperties: properties,
    },
    children: filteredChildren,
  }
}

function toMdast(node: HastContent) {
  if (node.type === 'text') {
    return {
      type: 'text',
      value: node.value,
    } as Text;
  }
  if (node.type === 'element') {
    const mdastNode = {
      type: 'admonitionHTML',
      data: {
        hName: node.tagName,
        hProperties: node.properties,
      },
      children: [],
    } as admonitionHTML;
    node.children.map(toMdast).forEach((child) => {
      if (child) {
        mdastNode.children.push(child);
      }
    });
    return mdastNode;
  }
  return null;
}

function htmlTemplate(
  type: string,
  title?: string | Content,
  children?: (Content | undefined | null | false)[],
) {
  const key = type in admonitionConfig ? type : 'note';
  const config = admonitionConfig[key];
  let titleNode  = null;
  if(typeof title === 'string') {
    titleNode = {
      type: 'text',
      value: title,
    } as Text;
  } else if (typeof title === 'undefined') {
    titleNode = {
      type: 'text',
      value: config.title,
    } as Text;
  } else {
    titleNode = title;
  }
  
  const iconNode = config.icon ? toMdast(fromHtml(config.icon, {
    space: 'svg',
    fragment: true,
  }).children[0]) : null;

  return h('div', {
    class: 'my-4 rounded-lg px-4 py-2 ' + config.class,
  }, [
    h('div', {
      class: 'flex items-center text-base font-bold',
    }, [iconNode, titleNode]),
    children && children.length > 0 && h('div', {
      class: 'mt-2 prose-compact text-sm',
    }, children)
  ])
}

export const fromMarkdown = (): FromMarkdownExtension => {
  const enterAdmonition: Handle = function(token) {
    this.enter<Admonition>({
      type: 'admonition',
      name: '',
      children: [],
    }, token);
  }
  const enterAdmonitionTitle: Handle = function(token) {
    this.enter<Paragraph>({
      type: 'paragraph',
      data: {
        admonitionTitle: true,
      },
      children: [],
    }, token);
  }
  const exitAdmonition: Handle = function(token) {    
    const node = this.exit(token) as Admonition;
    const type = node.name;
    const titleNodeIndex = node.children.findIndex((child) => {
      return child.type === 'paragraph' && child.data?.admonitionTitle;
    });
    const titleNode = titleNodeIndex >= 0
      ? node.children.splice(titleNodeIndex, 1)[0] as Paragraph
      : undefined;
    if (titleNode) {
      titleNode.data = {
        ...titleNode.data,
        hName: 'span'
      }
    }
    const subtree = htmlTemplate(type, titleNode, node.children);
    if (subtree) {
      Object.assign(node, subtree);
    }
  }
  const exitAdmonitionName: Handle = function(token) {
    const node = this.stack[this.stack.length - 1] as Admonition;
    if (node.type === 'admonition') {
      node.name = this.sliceSerialize(token);
    }
  }
  const exitAdmonitionTitle: Handle = function(token) {
    this.exit(token);
  }
  return {
    enter: {
      admonition: enterAdmonition,
      admonitionTitle: enterAdmonitionTitle,
    },
    exit: {
      admonition: exitAdmonition,
      admonitionName: exitAdmonitionName,
      admonitionTitle: exitAdmonitionTitle,
    }
  }
}

完善插件

import type { RemarkPlugin } from '@astrojs/markdown-remark';
import { syntax } from './syntax';
import { fromMarkdown } from './fromMarkdown';

const remarkAdmonition: RemarkPlugin<[]> = function() {
  const data = this.data();

  function add(key: string, value: unknown) {
    if (Array.isArray(data[key])) {
      (data[key] as unknown[]).push(value);
    } else {
      data[key] = [value];
    }
  }
  add('micromarkExtensions', syntax());
  add('fromMarkdownExtensions', fromMarkdown());

}
export default remarkAdmonition;

嗨，今天我们来聊一下怎么给 Markdown 扩展新语法吧。这篇文章是本教程的上篇，在这篇里你将会看到如何通过编写扩展的方法，给 remark.js 添加自定义的语法支持。

请注意，该文章中涉及到的内容将不限于JavaScript/TypeScript编程、编译原理、胡言乱语、灌水以及味同嚼蜡的流水账，如果您有任何不适，请及时停止阅读。

起因

Markdown 是一个非常实用便捷的富文本标记语言，但是 CommonMark 支持的语法毕竟是有限的，为了拓展 Markdown 的功能，不同平台通常会支持创建一些自定义标签，例如 {% note %}...{% endnote %}。这种标签功能极大程度上丰富了 Markdown 的生态，但是遗憾的是，这些拓展功能通常与平台绑定。你可以看到，这个站点目前使用了基于 remark 的 Markdown 解析器，通过编写 remark 插件，我们可以拓展 Markdown 语法，来实现一些自定义的功能。

remark 解析器常见于一些站点生成器上，如 Gatsby.js、Astro.js 等等。同时，它也是 MDX 的核心解析器。既然谈到了 MDX，你可能会问”为什么不直接用MDX呢？”。Well，我认为，在非动态内容上使用 MDX 是一种冗余，除非真的有交互需求。还有一点是，Vscode 下 MDX 语法高亮插件好像不太聪明的样子……

remark 技术栈

开始之前，我们先来了解一下，为了实现一个新语法，我们应该知道什么。

remark 的执行机制

remark 实际上是 unified.js 的一个插件，一串 Markdown 文本需要经过如下流程才能被解析为 HTML：·

MDAST 是 remark产生的语法树，在得到 MDAST 后需要使用 remark-rehype 插件将 MDAST 转换为 HAST，也就是 rehype 这个插件（用来解析HTML 的 unified 插件）的语法树。这样我们就能接驳 rehype 的生态，并输出 html。当然，文章不涉及 rehype 的生态。

我们把重点放在 remark 如何解析输入为语法树。有一些重点需要说明：

1. remark 底层使用了 micromark 解析 markdown 语法为 token；
2. remark 使用了 mdast-util-from-markdown 插件辅助将 token 序列 转换为 MDAST;
3. micromark 和 mdast-util-from-markdown 均支持编写 extension；

关于这套工具链的流程，discussion 中的回答可能会帮助你理解。

1. Input            | .~~~~ ['#','F','o','o','EOL'] <~~~ file.md
                    | |
2. Tokenize         | `~~~~ micromark(string)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~.
                    |                                                          o)-- micromarkExtension()
3. Token Stream     | .~~ ['enter:atxHeading','F','o','o','exit:atxHeading'] ~~'
                    | |
4. Grow Syntax Tree | `~~~> mdast-util-from-markdown(tokens) ~~~~~~~~~~~~~~~~~~.
                    |                                                 o        o)-- fromMarkdownExtension()
5. Transform Tree   | .~~~~~ transform(treeNode) => treeNode ~~~~~~~ / \  ~~~~~'
                    | |                                             o   o
6. Serialize        | `~~~~ mdast-util-to-markdown(tree) ~~~~~~~~~~~~~~~~~~~~~~.
                    |                                                          o)-- toMarkdownExtension()
7. Output           | <~~~~ ['#','F','o','o','EOL'] <~~~~~~~~~~~~~~~~~~~~~~~~~~'

如何编写一个 Rrmark 扩展

为了编写一个完整的语法扩展，我们需要做的事情有

1. 编写一个 micromark 扩展；
2. 编写一个 mdast-util-from-markdown 扩展；
3. 编写一个 remark 扩展；

嗯，也行你会注意到，micromark 似乎是用来做词法分析的，而 mdast-util-from-markdown 是用来做语法分析的。确实如此，不过之后的内容可能与你在课堂上学的内容有所不同。

micromark 扩展

函数式状态机

问：micromark 如何 tokenize markdown 语法的文本呢？
答：当然是状态机啦，不过这个状态机在我看来，应该是一个 NFA 而不是 DFA，而且写法上是函数式的。函数式状态机写法并不多见，但 golang 的词法分析器 就用了这种模式。

函数式的状态机大概有如下方式编写：

function state_1(code) {
    if (code === 'a') return state_1;
    return state_2;
}
function state_2(code) {
    if (code === 'b') return state_2;
    return state_1;
}

表示一个这样的状态机

函数表示一个状态，并且返回一个函数，表示下一个状态，状态的转换逻辑写在函数内部，也就是说，状态转换关系是隐式的（implicit）。 状态函数通过一个循环不断调用，直到遇到终止状态。大概长这个样子

state = initial_state;
while (!end_state) {
    state = state(code);
}

在 micromark 中，状态的typescript 类型定义如下：

/**
 * A character code.
 *
 * This is often the same as what `String#charCodeAt()` yields but micromark
 * adds meaning to certain other values.
 *
 * `null` represents the end of the input stream (called eof).
 * Negative integers are used instead of certain sequences of characters (such
 * as line endings and tabs).
 */
export type Code = number | null
/**
 * The main unit in the state machine: a function that gets a character code
 * and has certain effects.
 *
 * A state function should return another function: the next
 * state-as-a-function to go to.
 *
 * But there is one case where they return void: for the eof character code
 * (at the end of a value).
 * The reason being: well, there isn’t any state that makes sense, so void
 * works well.
 * Practically that has also helped: if for some reason it was a mistake, then
 * an exception is throw because there is no next function, meaning it
 * surfaces early.
 */
export type State = (code: Code) => State | void

编写一个 tokenizer

问：micromark 的 tokenizer 怎么编写？
答：tokenizer 是一个函数，你需要在 tokenizer 中编写需的状态函数，然后返回初始化状态函数。tokenizer 函数提供了一个 effects 参数，用来表示状态函数的副作用，例如创建 token、读取下一个字符，以及一个 ok 和 nok 参数，用来结束状态机。

问：micromark 中如何创建 token？
答：首先需要知道的是，micromark 中的 token 支持嵌套，具体通过维护一个 events 序列，包含 token 的 enter 和 exit 事件，来表示嵌套关系。然后通过 effects.enter(type, fields) 创建一个 token enter 事件，通过 effects.exit(type) 创建一个 token exit 事件。这也许就是 micromark 和一般编程语言编译器不一样的地方——它并不直接存储 token。

const tokenize: Tokenizer = function(effects, ok, nok) {
    const start: State = function(code) {
        // ...
        return ok(code);
    };
    // ...
    return start;
}

effects 提供了诸多便捷的方法，常用的有

// 用来表示打开一个 Token
effects.enter(type: string, fields: Record<string, unknown>): Token
// 用来表示关闭一个 Token
effects.enter(type: string): Token
// 用来消费一个字符，这会导致当前字符指向下一个字符
effects.consume(code: Code) => void
// 用来进行一次尝试解析， 若成功则保持解析结果并转到 returnState，若失败则回退解析结果，并跳到 bogusState
effects.attempt(
  construct: Construct | Construct[] | ConstructRecord,
  returnState: State,
  bogusState?: State | undefined
) => (code: Code) => void
// 与 appempt 相似，但是不会保留解析结果，根据成功与否跳到 returnState 或 bogusState
effects.check(
  construct: Construct | Construct[] | ConstructRecord,
  returnState: State,
  bogusState?: State | undefined
) => (code: Code) => void
// 与 check 相似，但是以打断当前块的方式尝试（tokenizer 中 this.interrupt = true）
effects.interrupt(
  construct: Construct | Construct[] | ConstructRecord,
  returnState: State,
  bogusState?: State | undefined
) => (code: Code) => void

当然，你也可以看看源代码中，这些类型是如何定义的，以有一个更深的理解。

完善 micromark 扩展

我们还需要将 tokenizer 包装在一个 Construct 中，它表示 markdown 文本中一种语法结构。

const your_syntax_name: Construct = {
  name: 'your_syntax_name',
  tokenize: tokenizeSpoiler
}

然后导出扩展，并定义语法的头字符，micromark 用这个字符优化解析性能

const syntax = (): MicromarkExtension => {
  return {
    text: {
      [your_head_code]: your_syntax_name,
    }
  }
}

不过需要提醒的是，micromark 有两种 Construct。一种是非容器 Construct，另一种是容器 Construct。上面的例子里举的是非容器 Construct，例如 **bold** 这就是一个非容器 Construct，而 blockquote、list 这种就属于容器 Construct。对于容器 Construct，你还需要定义一个 continuation tokenizer，表示解析其连续块，比如 blockquote 中

> first line will parsed by tokenizer.
> next line will parsed by continuation tokenizer.
> the content can include other fragments of markdown, so it's called container construct.
> > even multiple cascaded layer

Container Construct 需要这样定义

const your_syntax_name: Construct = {
  name: 'your_syntax_name',
  tokenize: tokenize,
  continuation: {
    tokenize: tokenizeContinuation,
  },
  exit: exit, // if your have a final hook
}

mdast-util-from-markdown 扩展

mdast-util-from-markdown 用起来就容易多了，有了前面的 token events 序列，mdast-util-from-markdown 需要提供处理这些事件的函数，具体来说这么用

自定义MDAST节点

为了利用 TypeScript 的类型系统，我们先给这个新节点一个定义

// define node type
export interface YourNodeType extends Parent {
  type: 'your_syntax_name',
  // you can add other fields here
}
// modify mdast module declaration
declare module 'mdast' {
  interface BlockContentMap {
    your_syntax_name: YourNodeType;
  }
}

根据具体需求的不同，你可以选择是否要继承 Parent 接口，该接口要求节点存在一个 children[] 字段。

构建 MDAST 语法树

然后用如下方法构造语法树上的新节点

const enter: Handle = function(token) {
  this.enter<YourNodeType>({
    type: 'your_syntax_name',
    // ... any other custom fields
    children: [],
  }, token);
  // ...
}
const exit: Handle = function(token) {
  this.exit(token);
  // ...
}
const config: Config = {
  enter: {
    your_syntax_name: enter,
    // ... any other token enter event handlers
  },
  exit: {
    your_syntax_name: exit,
    // ...
  }
}

enter handler 中的 this.enter 用来创建一个新的MDAST节点，此后所有解析出来的子节点都被添加到该节点的 children 中。直到 this.exit，也就是 exit handler 的执行，才退出这个新节点。

完善 mdast-util-from-markdown 扩展

最终，我们需要导出一个函数，该函数返回上文编写的 config 对象

export const fromMarkdown = (): FromMarkdownExtension => {
  return config;
}

remark 扩展

上面的流程已经完成了从字符串到 MDAST 的转换，接下来我们要完成从 MDAST 到 HAST 的转换

从 MDAST 到 HAST

从 MDAST 到 HAST 的转换规则由 remark-rehype 插件控制，更准确说，由 mdast-util-to-hast repo 这个工具实现。这个工具预设了 MDAST 中默认节点到到 HAST 的转换规则，对于非默认节点，工具会检查 MDAST 节点中 data 属性中是否包含 hName、hProperties、hChildren 这三个属性，并将它们作为 HAST 节点的 tagName、properties、children 属性。这样，我们只需要在 MDAST 节点中添加这几个属性，就能实现自定义节点到 HAST 的转换规则。

我们可以在 MDAST 节点创建的时候，就添加这些属性

const enter: Handle = function(token) {
  this.enter<YourNodeType>({
    type: 'your_syntax_name',
    data: {
      hName: 'div',
      hProperties: {
        // ... any other custom properties
      },
      hChildren: [],
    }
    children: [],
  }, token);
  // ...
}

或者也可以在 this.enter 时，或构造完 MDAST 后，再遍历修改节点，这取决于你 HAST 节点中的属性是否依赖于后续的解析结果。

完善 remark 扩展

如果上述工作你都完成了，那么接下来，我们来完成这个 remark 扩展吧

import { syntax } from './syntax';
import { fromMarkdown } from './fromMarkdown';

const remarkAdmonition: Plugin<[], Root> = function() {
  const data = this.data();
  function add(key: string, value: unknown) {
    if (Array.isArray(data[key])) {
      (data[key] as unknown[]).push(value);
    } else {
      data[key] = [value];
    }
  }
  add('micromarkExtensions', syntax());
  add('fromMarkdownExtensions', fromMarkdown());

}

上述代码中，add 函数用来向 processor 的 data 的某个属性中添加新的值，我们向 micromarkExtensions、fromMarkdownExtensions 添加了之前编写的扩展，这两个属性由 remark 定义，分别用来存储 micromark 和 mdast-util-from-markdown 的扩展。

好了，到此为止，我们的 remark 扩展就完成了，你可以在按照你所使用的平台提供的方式，为 remark 添加新的扩展了。

结语

呜呼，水完后才觉得，MDX 是真好用XD

实际上，remark 官方并不推荐编造自定义的语法，这样会导致迁移困难。他们更推荐使用remark-directive，这玩意写起来就像是在写HTML的标签一样

:::note{.warning title="note this"}
if you chose xxx, you should also use yyy somewhere…
:::

emmm，这么看确实不错。

ok，本篇文章仅涉及理论知识，下一篇文章里，我们将实战两个有趣的语法扩展，今天就先聊到这里吧~

Reference

1. unified repo
2. remark repo
3. rehype repo
4. remark-rehype repo
5. micromark repo
6. mdast-util-from-markdown repo
7. mdast-util-to-hast repo
8. github discussion: Why do we both need fromMarkdownExtensions and micromarkExtensions?
9. github discussion: How to tokenize multiline constructs? How to subtokenize their nested content?
10. CommonMark Spec

在部署深度学习模型时需要用到TensorRT，看了一遍文档后，我发现对于初学者来说，官方文档实在是太晦涩。文档里既没有接口的应用示例，也没有及时更新新接口的用法。在翻阅了部分博客和TensorRT仓库源码后，才有了本文。

TensorRT是NVIDIA推出的用于深度学习推理的高性能引擎，旨在优化深度神经网络模型的推理速度和性能。TensorRT可以通过层融合、混合精度、量化等技术显著提高深度神经网络的推理性能。

NVIDIA提供了TensorRT的C++和Python API，这里主要介绍Python API的一些用法。

1. TensorRT的安装

在安装TensorRT前，首先确保已经安装了CUDA和cuDNN。然后根据CUDA的版本在 下载页面 下载对应的TensorRT安装包。

不过貌似最新版本的TensorRT（8.6.1）支持从PyPI直接安装

pip install tensorrt

但是我只在Linux系统中安装成功了，Windows系统中安装失败，原因暂时不明。

1.1 Windows下的安装

Windows下需要使用Zip文件安装，根据 文档中 Zip File Installation 章节，下载zip包后：

1. 将压缩包内文件解压后，复制到 C:\Program Files\NVIDIA GPU Computing Toolkit\TensorRT\v8.x.x.x 下。安装路径随意选择。

2. 配置环境变量，将 <安装路径>/lib 和 <安装路径>/bin 添加到环境变量中。

3. 安装python包，进入 <安装路径>/python 目录，执行如下命令：

   pip install tensorrt-8.x.x-cp3x-none-win_amd64.whl
   

1.2 Linux下的安装

Linux下的安装比较简单，根据 文档中 Tar File Installation 章节，下载tar包后：

1. 解压tar包，进入解压后的目录。

   tar -xzvf TensorRT-8.x.x.x.Linux.x86_64-gnu.cuda-1x.x.tar.gz
   cd TensorRT-8.x.x.x
   

2. 添加环境变量

   vim ~/.bashrc
   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<安装路径>/lib
   export PATH=$PATH:<安装路径>/bin
   source ~/.bashrc
   

3. 安装python包

   cd TensorRT-8.x.x.x/python
   pip install tensorrt-8.x.x.x-cp3x-none-linux_x86_64.whl
   

2. 推理前的准备

TensorRT有自己的一套推理流程，我们在使用PyTorch或TensorFlow导出模型权重后，需要进一步转换。

TensorRT最终需要的是一个TensorRT Engine，这个Engine是由TensorRT的Builder构建，而Builder需要一个TensorRT Network。TensorRT Network是由TensorRT Parser解析的ONNX模型构建的。

当然，也有一些针对特定框架直接导出TensorRT Engine的工具，例如 torch2trt、 TF-TRT 等等，这里我用了更通用的方法，即先导出ONNX模型，再转换为TensorRT Engine。

我们还需要安装如下依赖，以备后续使用：

pip install onnx onnxruntime pycuda

2.1 导出ONNX模型

对于PyTorch模型，可以使用 torch.onnx.export 导出ONNX模型。

import torch
from model import Model

model = Model()
model.load_state_dict(torch.load('model.pth'))
model.eval()

dummy_input = torch.randn(1, 3, 224, 224)
torch.onnx.export(model, dummy_input, 'model.onnx', verbose=True)

对于TensorFlow模型，可以使用 tf.saved_model.save 导出SavedModel，再使用 tf2onnx 将SavedModel转换为ONNX模型。

import tensorflow as tf
import tf2onnx
import onnx
from model import Model

model = Model()
model.load_weights('model.h5')
model.compile()

input_signature = [tf.TensorSpec([3, 3], tf.float32, name='x')]
# Use from_function for tf functions
onnx_model, _ = tf2onnx.convert.from_keras(model, input_signature)
onnx.save(onnx_model, "dst/path/model.onnx")

2.2 转换为TensorRT Engine

为完成Engine的构建，我们需要完成的步骤有：

1. 转换并填充Network对象；
2. 编写构建配置对象（Config）；
3. 编写优化配置对象（Optimization Profile）；

TensorRT 默认为我们提供了三种主流格式的转换器：UffParser、CaffeParser、OnnxParser，在本文中我们需要使用OnnxParser。

TensorRT 支持两种批处理模式：显式批处理（explicit batch）和隐式批处理（implicit batch）。假设网络的输入张量形状为(n, c, h, w)，在隐式批处理模式下，网络只需要指定输入形状为(c, h, w)，批次维度是隐式的，并且在运行时可动态指定；在显式批处理模式下，批量维度需要网络显示定义，甚至可以不用批量维度，对于动态批量大小的需求，可以使用Optimization Profile配置动态形状。隐式批处理由早期TensorRT使用，现在已经被弃用了，许多教程中你会发现代码中出现了builder.max_batch_size = 32这样的调用，这就隐式批处理的相关配置，现在已经不赞成使用。

为开启显示批处理，需要：

builder = trt.Builder(...)
builder.create_network(1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH))

Optimization Profile支持配置网络输入的动态形状，比如动态批次大小、动态图像输入大小。为实现动态形状输入，我们需要指定输入张量的三个形状配置：最小尺寸、最优尺寸、最大尺寸。

min_shape = (3, 100, 200)
opt_shape = (3, 150, 250)
max_shape = (3, 200, 300)
profile = builder.create_optimization_profile();
profile.set_shape("input", min_shape, opt_shape, max_shape) 
config.add_optimization_profile(profile)

TensorRT支持设置多个优化配置文件，在运行时，需要设置优化配置文件，默认隐式选择配置文件0。你可以通过以下接口手动更改当前优化配置，需要注意的是，一个Engine可以有多个Context，但一个优化配置文件只能有一个Context。 优化配置文件的使用还有许多细节需要留意，更多请参考TensorRT文档 Working with Dynamic Shapes 章节

context.set_optimization_profile_async(0, stream)

有了以上基础，我们可以编写一个函数，将ONNX模型转换为TensorRT Engine。

import tensorrt as trt

TRT_LOGGER = trt.Logger(trt.Logger.INFO)

def GiB(val):
    return val * 1 << 30

# This function builds an engine from a onnx model.
def build_engine(onnx_file_path, precision = 'fp32', dynamic_shapes = None):
    """Takes an ONNX file and creates a TensorRT engine to run inference with"""

    EXPLICIT_BATCH_FLAG = 1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH)

    builder = trt.Builder(TRT_LOGGER)
    network = builder.create_network(EXPLICIT_BATCH_FLAG)
    config = builder.create_builder_config()
    parser = trt.OnnxParser(network, TRT_LOGGER)

    # Parse model file
    TRT_LOGGER.log(TRT_LOGGER.INFO, f'Loading ONNX file from path {onnx_file_path}...')
    with open(onnx_file_path, 'rb') as model:
        TRT_LOGGER.log(TRT_LOGGER.INFO, 'Beginning ONNX file parsing')
        if not parser.parse(model.read()):
            for error in range(parser.num_errors):
                TRT_LOGGER.log(TRT_LOGGER.ERROR, parser.get_error(error))
            raise ValueError('Failed to parse the ONNX file.')
    TRT_LOGGER.log(TRT_LOGGER.INFO, 'Completed parsing of ONNX file')
    TRT_LOGGER.log(TRT_LOGGER.INFO, f'Input number: {network.num_inputs}')
    TRT_LOGGER.log(TRT_LOGGER.INFO, f'Output number: {network.num_outputs}')
    
    
    if dynamic_shapes is not None:
        # set optimization profile for dynamic shape
        profile = builder.create_optimization_profile()
        for i in range(network.num_inputs):
            input = network.get_input(i)
            min_shape = dynamic_shapes['min_shape']
            opt_shape = dynamic_shapes['opt_shape']
            max_shape = dynamic_shapes['max_shape']
            profile.set_shape(input.name, min_shape, opt_shape, max_shape)
        config.add_optimization_profile(profile)

    # We set the builder batch size to be the same as the calibrator's, as we use the same batches
    # during inference. Note that this is not required in general, and inference batch size is
    # independent of calibration batch size.
    config.set_memory_pool_limit(trt.MemoryPoolType.WORKSPACE, GiB(1)) # 1G
    
    if precision == 'fp32':
        pass
    elif precision == 'fp16':
        config.set_flag(trt.BuilderFlag.FP16)
    elif precision == 'int8':
        config.set_flag(trt.BuilderFlag.INT8)
    else:
        raise ValueError('precision must be one of fp32, fp16, or int8')

    # Build engine.
    TRT_LOGGER.log(TRT_LOGGER.INFO, f'Building an engine from file {onnx_file_path}; this may take a while...')
    serialized_engine = builder.build_serialized_network(network, config)
    TRT_LOGGER.log(TRT_LOGGER.INFO, 'Completed creating Engine')
    return serialized_engine

3.3 保存TensorRT Engine

序列化和反序列化TensorRT Engine的代码如下：

def save_engine(engine, path):
    TRT_LOGGER.log(TRT_LOGGER.INFO, f'Saving engine to file {path}')
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    with open(path, 'wb') as f:
        f.write(engine)
    TRT_LOGGER.log(TRT_LOGGER.INFO, 'Completed saving engine')

def load_engine(path):
    logger.info(f'Loading engine from file {path}')
    runtime = trt.Runtime(logger.TRT_LOGGER)
    with open(path, 'rb') as f:
        engine = runtime.deserialize_cuda_engine(f.read())
    logger.info('Completed loading engine')
    return engine

3. 使用TensorRT进行推理

上文中提到了网络输入张量支持动态形状，同样的，输出张量也支持动态形状，比如网络输出形状由网络输入形状决定，为此，我们需要编写一些分配内存的策略。 在内存分配上，我们需要一点CUDA编程相关的知识，具体来说，使用pycuda分配内存（实际上更建议使用cudart）。在CUDA内存模型中，Host指电脑主机，Device指NVIDIA显卡。

我们需要派生IOutputAllocator类，然后实现自己的reallocate_output和notify_shape方法。reallocate_output中可以实现的内存分配方案很灵活，这里使用的是每次都重新申请内存，显然这样是不优的，这样做的好处是代码量少，另一些可选的方案有：

1. 预分配足够大的内存，可以使用context.get_max_output_size(output_tensor_name)来获取优化配置文件中的最大字节数；
2. 重新利用上一次分配的内存空间，仅当空间不足时才重新分配；
3. …

from collections import OrderedDict
import tensorrt as trt
import pycuda.driver as cuda
import numpy as np

class OutputAllocator(trt.IOutputAllocator):
    def __init__(self):
        # print("[MyOutputAllocator::__init__]")
        super().__init__()
        self.buffers = {}
        self.shapes = {}

    def reallocate_output(self, tensor_name: str, memory: int, size: int, alignment: int) -> int:
        # print("[MyOutputAllocator::reallocate_output] TensorName=%s, Memory=%s, Size=%d, Alignment=%d" % (tensor_name, memory, size, alignment))
        if tensor_name in self.buffers:
            del self.buffers[tensor_name]
        
        address = cuda.mem_alloc(size)
        self.buffers[tensor_name] = address
        return int(address)
        
    def notify_shape(self, tensor_name: str, shape: trt.Dims):
        # print("[MyOutputAllocator::notify_shape] TensorName=%s, Shape=%s" % (tensor_name, shape))
        self.shapes[tensor_name] = tuple(shape)

然后封装一个用于推理的类，该类提供一个 infer 接口，接收一个输入列表或字典，返回一个输出字典。列表和字典的值是numpy数组。当输入为列表时，列表中的元素将按顺序传入模型。为了顺利执行推理，我们需要在推理前将输入张量从host转移到device上，在推理后将输出张量从device转移到host上。基于index的张量方法已经被弃用，在新版本TensorRT中建议使用基于name的张量方法。

以下代码使用了异步方法，需要用到cuda stream，关于cuda stream的概念和用法，可以参考CUDA文档 Streams 章节

from collections import OrderedDict
from typing import Dict, OrderedDict, List, Union
import tensorrt as trt
import numpy as np
import pycuda.driver as cuda
import pycuda.autoinit

def get_input_tensor_names(engine: trt.ICudaEngine) -> list[str]:
    input_tensor_names = []
    for binding in engine:
        if engine.get_tensor_mode(binding) == trt.TensorIOMode.INPUT:
            input_tensor_names.append(binding)
    return input_tensor_names

def get_output_tensor_names(engine: trt.ICudaEngine) -> list[str]:
    output_tensor_names = []
    for binding in engine:
        if engine.get_tensor_mode(binding) == trt.TensorIOMode.OUTPUT:
            output_tensor_names.append(binding)
    return output_tensor_names

class ProcessorV3:
    def __init__(self, engine: trt.ICudaEngine):
        # # 选择第一个可用的 GPU 设备
        # device = cuda.Device(0)
        # # 将所选设备设置为当前活动的上下文
        # self.cuda_context = device.make_context()
        # self.cuda_context.push()
        
        self.engine = engine
        self.output_allocator = OutputAllocator()
        # create execution context
        self.context = engine.create_execution_context()
        # get input and output tensor names
        self.input_tensor_names = get_input_tensor_names(engine)
        self.output_tensor_names = get_output_tensor_names(engine)
        # create stream
        self.stream = cuda.Stream()
        # Create a CUDA events
        self.start_event = cuda.Event()
        self.end_event = cuda.Event()
        
    # def __del__(self):
    #     self.cuda_context.pop()
        
    def get_last_inference_time(self):
        return self.start_event.time_till(self.end_event)
        
    def infer(self, inputs: Union[Dict[str, np.ndarray], List[np.ndarray], np.ndarray]) -> OrderedDict[str, np.ndarray]:
        """
        inference process:
        1. create execution context
        2. set input shapes
        3. allocate memory
        4. copy input data to device
        5. run inference on device
        6. copy output data to host and reshape
        """
        # set input shapes, the output shapes are inferred automatically

        if isinstance(inputs, np.ndarray):
            inputs = [inputs]
        if isinstance(inputs, dict):
            inputs = [inp if name in self.input_tensor_names else None for (name, inp) in inputs.items()]
        if isinstance(inputs, list):
            for name, arr in zip(self.input_tensor_names, inputs):
                self.context.set_input_shape(name, arr.shape)

        buffers_host = []
        buffers_device = []
        # copy input data to device
        for name, arr in zip(self.input_tensor_names, inputs):
            host = cuda.pagelocked_empty(arr.shape, dtype=trt.nptype(self.engine.get_tensor_dtype(name)))
            device = cuda.mem_alloc(arr.nbytes)
            
            host[:] = arr
            cuda.memcpy_htod_async(device, host, self.stream)
            buffers_host.append(host)
            buffers_device.append(device)
        # set input tensor address
        for name, buffer in zip(self.input_tensor_names, buffers_device):
            self.context.set_tensor_address(name, int(buffer))
        # set output tensor allocator
        for name in self.output_tensor_names:
            self.context.set_tensor_address(name, 0) # set nullptr
            self.context.set_output_allocator(name, self.output_allocator)
        # The do_inference function will return a list of outputs
        
        # Record the start event
        self.start_event.record(self.stream)
        # Run inference.
        self.context.execute_async_v3(stream_handle=self.stream.handle)
        # Record the end event
        self.end_event.record(self.stream)

        # self.memory.copy_to_host()
        
        output_buffers = OrderedDict()
        for name in self.output_tensor_names:
            arr = cuda.pagelocked_empty(self.output_allocator.shapes[name], dtype=trt.nptype(self.engine.get_tensor_dtype(name)))
            cuda.memcpy_dtoh_async(arr, self.output_allocator.buffers[name], stream=self.stream)
            output_buffers[name] = arr
        
        # Synchronize the stream
        self.stream.synchronize()
        
        return output_buffers

使用示例：

inputs = {
  'image': np.array(...),
}

engine = load_engine(...)
processor = ProcessorV3(engine)

outputs = processor.infer(inputs)

4. 后记

有一个需要注意的地方，TensorRT生成的Engine是和硬件相关的，不同型号的显卡不能通用这个Engine。

当然，如果只是按照前文这种用法的话，体现不出使用TensorRT的优势。TensorRT的另一个功能是低精度推理，支持模型量化，但这又是另一个体系庞大的故事了，这里先挖一个坑，以后慢慢填。

还有一点待优化的是，CUDA是支持多个Stream并行执行的，但是上述代码并没有体现这一点，这个作为CUDA编程的一个坑，先留一下。

5. 参考资料

1. NVIDIA 开发者手册
2. NVIDIA TensorRT 中文版开发手册
3. TensorRT Python API文档
4. TensorRT C++ API文档
5. TensorRT 的介绍与应用
6. PyCUDA 文档
7. CUDA C++ Programming Guide
8. CUDA Python Manual
9. “CUDA Stream” from Lei Mao’s blog
10. “Page-Locked Host Memory for Data Transfer” from Lei Mao’s blog

Toc

1. SQL 数据库操作
   1. 创建数据库 CREATE DATABASE
   2. 删除数据库 DROP DATABASE
   3. 重命名数据库 RENAME DATABASE
   4. 选择数据库 USE
   5. 显示语句 SHOW
2. SQL 表操作
   1. 创建表 CREATE TABLE
   2. 更改表结构 ALTER TABLE
      1. 添加新字段
      2. 修改字段属性
      3. 删除字段
   3. 删除表 DROP TABLE
   4. 清空表 TRUNCATE TABLE
   5. 重命名表 RENAME TABLE
3. SQL 约束
   1. 主键约束
   2. 外键约束
   3. 唯一约束
   4. 非空约束
   5. 默认约束
   6. 检查约束
4. SQL 索引
   1. 创建索引
   2. 删除索引
5. SQL 中的数据类型
   1. 整数
   2. 浮点数
   3. 定点数
   4. 字符串
   5. 日期
   6. 其他
6. 参考

SQL 数据库操作

创建数据库 CREATE DATABASE

CREATE DATABASE [IF NOT EXISTS] <数据库名称>;

数据库名称在RDBMS中必须是唯一的。

删除数据库 DROP DATABASE

DROP DATABASE [IF EXISTS] <数据库名称>;

重命名数据库 RENAME DATABASE

RENAME DATABASE [IF EXISTS] <旧名称> TO <新名称>;
-- 这是MySQL的语法，不同数据库管理系统可能有不同的语法

选择数据库 USE

选择当前要进行操作的数据库

USE <数据库名称>;

显示语句 SHOW

MySQL使用 SHOW 命令实际上就是对 information_schema 表执行 SELECT 。

SHOW DATABASES; -- 显示主机所有数据库
SHOW TABLES; -- 显示当前数据库的所有表
SHOW COLUMNS; -- 显示当前表的结构
DESCRIBE; -- 和SHOW COLUMNS等价
SHOW CREATE DATABASE|SCHEMA <数据库名>\G --显示创建某个数据库的命令
-- \G为按列打印 \g等同于;
SHOW CREATE TABLE <表名>\G -- 显示创建某个表的命令
SHOW INDEX FROM <表名>\G -- 显示某个表的索引

更多用法请参考官方手册：https://dev.mysql.com/doc/refman/8.0/en/show.html

SQL 表操作

创建表 CREATE TABLE

CREATE TABLE [IF NOT EXISTS] <表名>(
    <字段1> <类型> <默认值> <字段约束>,
    <字段2> <类型> <默认值> <字段约束>,
    ...,
    <表约束>
);

更改表结构 ALTER TABLE

• 使用 ADD 子句添加新字段。
• 使用 MODIFY 子句修改字段的属性，例如：约束，默认值等。
• 使用 DROP 子句删除字段。

添加新字段

ALTER TABLE [IF EXISTS] <表名>
ADD <新字段> <类型> <字段约束> [AFTER <已有字段>];

如果要在表中指定新字段的顺序，可以使用可选子句 AFTER <已有字段> ，使新字段添加在已有字段之后。默认添加在最后一列。

修改字段属性

ALTER TABLE [IF EXISTS] <表名>
MODIFY <字段名> <类型> <默认值> <字段约束>;

-- 在MySQL中还可以使用CHANGE语法，可以直接重命名
ALTER TABLE [IF EXISTS] <表名>
CHANGE <旧字段名> <新段名> <类型> <默认值> <字段约束>;

应该修改没有数据的表的字段的属性。 因为更改已包含数据的表中字段的属性可能会导致永久性数据丢失。 例如，如果列的数据类型为VARCHAR，并且将其更改为 INT ，则数据库系统必须将数据从 VARCHAR 转换为 INT 。 如果转换失败，数据库系统可能会使用列的默认值，这可能与预期不符。

删除字段

ALTER TABLE [IF EXISTS] <表名>
DROP <字段1>,
DROP <字段2>,
...;

删除表 DROP TABLE

DROP TABLE [IF EXISTS] <表名>;

为了防止删除不存在的表的错误，使用可选子句 IF EXISTS 。 如果使用 IF EXISTS 选项，如果删除一个不存在的表，数据库系统将不会抛出任何错误。 某些数据库系统会发出警告或通知。

清空表 TRUNCATE TABLE

DELETE 对删除百万行的大表效率较低，使用 TRUNCATE 更高效。

TRUNCATE TABLE [IF EXISTS] <表名>;
TRUNCATE TABLE [IF EXISTS] <表1>,<表2>,...;

TRUNCATE [IF EXISTS] <表名>;
-- 有些数据库（如MySQL）允许省略TABLE

重命名表 RENAME TABLE

RENAME TABLE [IF EXISTS] <旧表名> TO <新表名>;
-- 下面是一个等价的写法
ALTER TABLE [IF EXISTS] <旧表名> RENAME <新表名>;

SQL 约束

主键约束

对于关系表，通过主键字段可以唯一区分不同的记录，任意两条记录的主键值不能相同，主键设定好后一般不要再修改，作为主键最好是完全业务无关的字段，我们一般把这个字段命名为 id。常见的可作为 id 字段的类型有自增整数类型、全局唯一 GUID 类型。

• 创建主键约束

-- 创建表时设置主键
CREATE TABLE <表名> (
    <字段1> <类型> PRIMARY KEY,
    <字段2> <类型>,
    ...
);

-- 使用表级约束
CREATE TABLE <表名> (
    <字段1> <类型>,
    <字段2> <类型>,
    ...
    PRIMARY KEY(字段1 [,字段2,...]) -- 可以设置多个字段为联合主键
);

-- 使用表级约束并对约束起名
CREATE TABLE <表名> (
    <字段1> <类型>,
    <字段2> <类型>,
    ...
    CONSTRAINT <约束名称> PRIMARY KEY(字段1 [,字段2,...])
);

-- 向已创的表添加主键约束
ALTER TABLE <表名>
ADD PRIMARY KEY (字段1 [,字段2,...]);

-- 添加约束时也可以起名
ALTER TABLE <表名>
ADD CONSTRAINT <约束名> PRIMARY KEY (字段1 [,字段2,...]);

• 删除主键约束

-- 有名称的约束都可以这样删除
ALTER TABLE <表名>
DROP CONSTRAINT <约束名>;

-- 或者直接这样
ALTER TABLE <表名>
DROP PRIMARY KEY;

外键约束

外键用来在两张关系表之间建立联系，将当前表一些值对应到另一张表的主键上，形成对应关系，这样就创建的两张表之间的链接，称第二张表的主键为当前表的外键。

• 创建外键约束

-- 定义表时创建外键约束
CREATE TABLE <表1> (
    <字段> <类型>,
    ...
    FOREIGN KEY (字段)
        REFERENCES <表2> (外键字段)
);

-- 为约束起名
CREATE TABLE <表1> (
    <字段> <类型>,
    ...
    CONSTRAINT <约束名称> FOREIGN KEY (字段)
        REFERENCES <表2> (外键字段)
);

-- 向已创的表添加外键约束
ALTER TABLE <表1>
ADD FOREIGN KEY (字段)
    REFERENCES <表2> (外键字段)

-- 添加约束时也可以起名
ALTER TABLE <表1>
ADD CONSTRAINT <约束名> FOREIGN KEY (字段)
    REFERENCES <表2> (外键字段);

• 删除外键约束

ALTER TABLE <表名>
DROP CONSTRAINT <约束名>;

-- 或者这样
ALTER TABLE <表名>
DROP FOREIGN KEY <约束名>; 
-- 如果创建时没有定义约束名，数据库系统会自动生成一个，可以用其他命令查询

唯一约束

唯一约束用来确保某个或某组字段在每个记录中都是唯一的。

• 创建唯一约束

-- 创建表时设置唯一约束
CREATE TABLE <表名> (
    <字段1> <类型> UNIQUE,
    <字段2> <类型>,
    ...
);

-- 使用表级约束
CREATE TABLE <表名> (
    <字段1> <类型>,
    <字段2> <类型>,
    ...
    UNIQUE(字段1 [,字段2,...]) -- 可以设置多个字段联合
);

-- 使用表级约束并对约束起名
CREATE TABLE <表名> (
    <字段1> <类型>,
    <字段2> <类型>,
    ...
    CONSTRAINT <约束名称> UNIQUE(字段1 [,字段2,...])
);

-- 向已创的表添加唯一约束
ALTER TABLE <表名>
ADD UNIQUE (字段1 [,字段2,...]);

-- 添加约束时也可以起名
ALTER TABLE <表名>
ADD CONSTRAINT <约束名> UNIQUE (字段1 [,字段2,...]);

• 删除唯一约束

ALTER TABLE <表名>
DROP CONSTRAINT <约束名>;

-- 或者这样
ALTER TABLE <表名>
DROP UNIQUE <约束名>; 
-- 如果创建时没有定义约束名，数据库系统会自动生成一个，可以用其他命令查询

非空约束

非空约束用来确保插入记录的某个字段不能为空（即 NULL ）

-- 创建约束，非空约束没有表级定义
CREATE TABLE <表名> (
    <字段1> <类型> NOT NULL,
    <字段2> <类型>,
    ...
);
-- 添加约束
ALTER TABLE <表名>
MODIFY <字段名> <类型> NOT NULL; -- 先要确保字段没有NULL值
-- 删除约束
ALTER TABLE <表名>
MODIFY <字段名> <类型> NULL;

默认约束

默认约束用来确定字段未指定时的默认值。

-- 创建约束，默认约束没有表级定义
CREATE TABLE <表名> (
    <字段1> <类型> DEFAULT <值>,
    <字段2> <类型>,
    ...
);
-- 添加约束
-- MySQL用法:
-- ALTER COLUMN这种语法仅见于修改DEFAULT值和一些其他不常用地方
ALTER TABLE <表名>
ALTER <字段名> SET DEFAULT <值>;
-- 删除约束
ALTER TABLE <表名>
ALTER <字段名> DROP DEFAULT;
-- 当然也可以通过MODIFY添加和删除

检查约束

检查约束允许我们自定义新添加值是否合法。MySQL 8.0.16 之前的版本是默认忽略检查约束的。

• 创建检查约束

-- 创建表时设置检查约束
CREATE TABLE <表名> (
    <字段1> <类型> CHECK(条件表达式),
    <字段2> <类型>,
    ...
);

-- 使用表级约束
CREATE TABLE <表名> (
    <字段1> <类型>,
    <字段2> <类型>,
    ...
    CHECK(条件表达式)
);

-- 使用表级约束并对约束起名
CREATE TABLE <表名> (
    <字段1> <类型>,
    <字段2> <类型>,
    ...
    CONSTRAINT <约束名称> CHECK(条件表达式)
);

-- 向已创的表添加检查约束
ALTER TABLE <表名>
ADD CHECK(条件表达式);

-- 添加约束时也可以起名
ALTER TABLE <表名>
ADD CONSTRAINT <约束名> CHECK(条件表达式);

• 删除检查约束

ALTER TABLE <表名>
DROP CONSTRAINT <约束名>;

-- 或者这样
ALTER TABLE <表名>
DROP CHECK <约束名>; 
-- 如果创建时没有定义约束名，数据库系统会自动生成一个，可以用其他命令查询

SQL 索引

数据库索引或索引，有助于加速从表中检索数据。当从表查询数据时，首先MySQL会检查索引是否存在，然后MySQL使用索引来选择表的精确物理对应行，而不是扫描整个表。所有主键列都是表的主索引。对于数据量小的表不需要建立索引。

创建索引

• 创建表时创建索引

MySQL自动将声明为PRIMARY KEY，KEY，UNIQUE或INDEX的任何列添加到索引。

• 向已有表添加索引

CREATE [UNIQUE|FULLTEXT|SPATIAL] INDEX <索引名>
[USING BTREE|HASH|RTREE] 
ON <表> (<字段> [(长度)] [ASC | DESC],...)

UNIQUE索引会对字段创建唯一约束，FULLTEXT、SPATIAL索引仅由MyISAM存储引擎支持，其中FULLTEXT索引仅在数据类型为CHAR，VARCHAR或TEXT的列中接受，SPATIAL索引列值不能为NULL。

不同的存储引擎有不同的索引类型

存储引擎	允许的索引类型
MyISAM	BTREE, RTREE
InnoDB	BTREE
MEMORY/HEAP	HASH, BTREE
NDB	HASH

删除索引

DROP INDEX <索引名> ON <表名>

-- 或者使用ALTER TABLE语法
ALTER TABLE <表名>
DROP INDEX <索引名>

SQL 中的数据类型

以MySQL为例

整数

可以指定整数的显示宽度INT(N) UNSIGNED ZEROFILL，宽度不足用0补全，宽度超过N则无视规则。注意只有设定了UNSIGNED ZEROFILL 才有效。

浮点数

可以设定浮点数小数位精度和有效数字精度 FLOAT(P,D) ：

• P是表示有效数字数的精度。 P范围为1〜65。
• D是表示小数点后的位数。D的范围是0~30。MySQL要求D<=P。

定点数

DECIMAL 数据类型用于在数据库中存储精确的数值。有 UNSIGNED 和 ZEROFILL 属性，也可以和浮点数一样设置小数位精度和有效数字精度，用法同浮点数。不指定精度默认为 DECIMAL(10, 0) 。

字符串

日期

其他

参考

1. https://www.w3cschool.cn/sql/
2. https://www.runoob.com/sql/sql-tutorial.html
3. https://www.yiibai.com/sql/
4. https://www.yiibai.com/mysql/
5. https://dev.mysql.com/doc/refman/8.0/en/

Toc

1. 简介
2. SQL 数据检索
   1. 基本检索 SELECT
   2. 条件检索 WHERE
   3. 检索结果排序 ORDER BY
   4. 检索结果截取 LIMIT
   5. 检索结果连接 JOIN
      1. JOIN链接
      2. 自连接
   6. 检索结果组合 UNION
   7. 检索结果分组 GROUP BY
   8. SQL 中的别名
3. SQL 数据操作
   1. 插入记录 INSERT
   2. 修改记录 UPDATE
   3. 删除记录 DELETE
4. SQL 函数
   1. SQL 中的合计函数
   2. SQL 中的其他常用函数
5. SQL运算符
   1. 算术运算符
   2. 比较运算符
   3. 逻辑运算符
      1. IN、ALL、ANY用法
      2. EXISTS、BETWEEN、LIKE用法
      3. IS NULL、IS NOT NULL用法
6. SQL表达式
   1. 布尔表达式
   2. 数值表达式
   3. 日期表达式
7. 参考