
首先直接來看看正規表示式本身：

```
^1?$|^(11+?)\1+$
```

仔細看一下可以發現該表示式是由兩個部分組合而成，`^1?$` 與 `^(11+?)\1+$`，當其中一個部分匹配時則整個表示式成功匹配。

其實，與其說這一串表示式是在尋找質數，不如說它其實是在匹配合數（Composite Number），而且搜尋的對象不是數字本身，而是將數字展開成許多個符號的排列。例如檢查`7`是否為質數時，其實是將其轉成連續7個1的字串，也就是`1111111`，然後再透過表示式檢查該字串是否為合數。

翻譯成 Python 的話大約如下：

```python
import re

def is_composite(n: int) -> bool:
    return re.match(r"^1?$|^(11+?)\1+$", "1" * n)
```

因此如果要檢查是否為質數，只要把是否為合數的結果反轉即可：

```python
def is_prime(n: int) -> bool:
    return not is_composite(n)
```

順手寫一下單元測試，驗證這一段表示式的功能性：

```python title="test_is_prime.py"
def test_is_prime():
    assert not is_prime(0)
    assert not is_prime(1)
    assert is_prime(2)
    assert is_prime(3)
    assert not is_prime(4)
    assert is_prime(5)
    assert not is_prime(6)  # 2 * 3
    assert is_prime(991)
    assert not is_prime(1001)  # 7 * 11 * 13
```

使用 pytest 執行：

```shell replEnabled replOptions={{commandGroupLines: "1"}}
pytest test_is_prime.py
==================== test session starts =====================
platform darwin -- Python 3.10.2, pytest-7.3.1, pluggy-1.0.0
rootdir: /Users/gocreating
plugins: anyio-3.6.2
collected 1 item

test_is_prime.py .                                      [100%]

===================== 1 passed in 0.01s ======================
```

# 拆解


## 符號說明

對正規表示式比較陌生的讀者可以複習一下此處使用到的符號：

- `^`: 字串開頭
- `$`: 字串結尾
- `?`: 至多匹配一次 Token (0次、1次)
- `+`: 至少匹配一次 Token (1次、2次、3次、...無限多次)
- `\1`: 最近一次匹配到的字串

## 使用 Python 模擬

憑空解釋此表示式背後的含義可能無助於理解實作的邏輯，此處我來試著將原始的表示式以 Python 陳述式的方式翻譯及模擬

```python
def is_composite(n: int) -> bool:
    # ^1?$
    def is_left_part_matched(s: str) -> bool:
        return ...

    # ^(11+?)\1+$
    def is_right_part_matched(s: str) -> bool:
        return ...

    s = "1" * n
    return is_left_part_matched(s) or is_right_part_matched(s)
```

### 第一部分

左半部分的 `^1?$` 字面上相當直觀，只匹配`1`出現0次及1次的情況，可以理解為 $n=0$ 或 $n=1$ 時皆視 $n$ 為合數：

```python
def is_left_part_matched(s: str) -> bool:
    return len(s) == 0 or len(s) == 1
```

此部分看來是在檢查特例情況及邊界。

### 第二部分

右半部分的 `^(11+?)\1+$` 可以先看括號內的 `11+?`，意義上其實是在執行迴圈尋找因數字串，括號右側的 `\1+` 則是拿著目前迭代到的因數字串去檢查能否藉由串接多個因數字串而湊出欲比對的字串。

如果湊得出來，則表示目前的因數可以整除 $n$，也就表示 $n$ 是和數。

```python
def is_right_part_matched(s: str) -> bool:
    for factor in range(2, n):
        # ^(11+?)
        captured_group = s[0:factor]
        # \1+
        accumulated_text = captured_group
        while len(accumulated_text) <= len(s):
            # $
            if accumulated_text == s:
                return True
            accumulated_text = f"{accumulated_text}{captured_group}"
    return False
```

# 分析與結語

雖然 One-liner 總是為人詬病，但是今天介紹的表示式除了簡潔以外，還充分體現了程式化的邏輯思維，有字串處理、有迭代、有演算法（Backtracking），甚至需要意識到正規表示式的完備性，實在不得不佩服原作者設計之巧妙。

雖然本文使用字元 `1` 當作範例，但理解原理之後，聰明的讀者們也可以自行更換為其他字元（如：`^x?$|^(xx+?)\1+$`）來達到相同效果！

本文改寫並啟發自 Hacker News #657 看到的原文 [A regular expression to check for prime numbers](https://www.noulakaz.net/2007/03/18/a-regular-expression-to-check-for-prime-numbers)。

使用正規表示式（Regular Expression）檢查質數


與同事閒聊之下得知了這本書，從書名就可以強烈感受到討論主題的生硬程度，也不是我熟悉與偏好的內容，但是秉持著想理解何謂正義的念頭，最終還是花了幾個月的時間慢慢啃完...約莫半本。

以前我總覺得社會上每天都有太多不公平的事情不斷發生，富人應該要繳更多稅、受苦的殘疾人士應該要能自由選擇安樂死、行人不該有無敵路權、...，但是從《正義》的觀點出發，我總算逐漸理解，所謂的不公平其實只是隨著主張利益的角度不同而產生的主觀意識。就以最著名的電車兩難來說好了，不論是犧牲少數人還是犧牲多數人，其實只是在眾人利益及個人利益之間取捨罷了，書中的每個例子最終都能收斂成不同利益之間的取捨。這很讓人感慨，世上並沒有完美的規則可以依循，每個族群都有他們想要捍衛的利益，也就不會有所有人都能接受的絕對公平與正義。

回想以前在社會課程裡學到的各種主義，像是資本主義、共產主義、民主主義，背後代表的便是特定國家或特定族群想強調的利益立場，台灣的民主制度代表多數人的意見，可以促成全民幸福感與效用的最大化，我認為屬於功利主義；中俄等國家的共產制度認為人民有義務為國家效勞，似乎是呼應了康德的正義流派；美國的資本至上則給人傾向自由放任主義的感覺。

不曉得是翻譯流暢度的關係還是哲學類書籍的特性，書中大量使用到雙重否定甚至三重否定，或是提及某些否面議題的反面論述時，總讓我腦袋的思路不停來回翻轉，頭腦不清醒或是下班拖著疲憊感時真心不建議閱讀此書。不過總的來說，本書仍然提供我許多以前未曾思考過的利益觀點——如果富人是因為自己的才華與努力而致富，那麼憑什麼要繳更多稅呢？如果受苦的殘疾人士可以決定自己安樂死與否，那麼人們是否能自由決定販售自己的器官或是結束生命呢？如果行人不遵守交通規則，排擠其他用路人的權益，憑什麼不能制裁？把上述這些以往我認為只能這麼做才能符合正義的例子拿出來，以新的利益觀點來檢視，好像原本我自認的正義反倒變成不公不義了。

經歷這一場思辨之旅，雖然我自己無法領悟所有道理，但還是小小刷新了道德感，期許你我未來都能以更全面、更宏觀的角度來看待這個社會。

觀書《正義：一場思辨之旅》

Hakari Puzzle 解謎遊戲


在著手開發以前，我基於手裡擁有的先備條件做了幾項架構性的決定。

# 使用 Design System 管理佈景主題

任職於前公司時，我曾開發過一套 Design System，名為 `Essence`，雖然它不是百分之百完美的實作，但是視覺上是中文友善的獨立的系統，不會有像是 Bootstrap 等拉丁語系框架套在方塊字上面的違和感，再從可用性來說，Essence 已經使用在兩款產品上，算是經得起考驗；對於整個系統的作者我來說，開發介面肯定也是最熟悉不過了。因此無論從視覺角度、串接成本角度、開發時程角度來說，在我的部落格套用 Essence 無疑是最好的選擇。

# 使用 Multi-Workspace Monorepo 管理程式碼

身為一個獨立開發者，我不需要與其他人協作，因此 Source Code 的管理上採用 Monorepo 的策略，可以藉此降低我的管理成本。由於我使用的技術棧是 JavaScript 生態圈，因此通常會搭配 Multi-workspace 來區隔不同子專案的職責，但又能達到共享程式碼的好處。如果考慮到未來我不止有部落格專案，可能會有各式各樣想要嘗試的題目，那麼 Multi-workspace 也可以讓我降低新建專案的成本。

我的檔案架構如下：

```
project_root/
  - README.md
  - package.json
  - packages/
    - utils/ <------------ 所有專案共享的模組
      - package.json
      - ...
    - essence/ <---------- 佈景主題
      - package.json
      - ...
    - personal-blog/ <---- 部落格專案
      - package.json
      - ...
    - future-project/ <--- 未來的新專案
      - package.json
      - ...
```

# React.js & Next.js

技術棧的挑選純粹是基於個人熟悉程度以及市場主流工具，因此使用 React.js 搭配 Next.js 框架。

# 靜態網站生成 (SSG, Static Site Generation)

我的每一篇文章都是一個 `MDX` 檔案，並且儲存於 Source Code 的檔案裡，這代表我不需要依賴外部的資料庫，不需要動態產生網站頁面，只需要在建置階段產生所有網站內容就能部署了。這麼做帶來了幾個好處：

- 省去伺服器成本
- 只需要 Host 靜態檔案，因此有很多免費 Hosting 服務可以選擇
- 網站內容已經預產好，因此載入速度可以很快，也支援 SEO
- 如果 Online Build 的免費額度耗盡了，可以切換成 Offline Build

基礎建設

使用 Multi-Workspace Monorepo 管理程式碼

靜態網站生成 (SSG, Static Site Generation)


# Vercel vs. Netlify

既然我們使用了 Next.js 作為主要開發框架，那麼主流的 Hosting 通常就是 Vercel 或是 Netlify 了，差別在於 Vercel 的免費方案是反對商業使用的，如果需要在站內刊登廣告或是販售商品，建議可以使用 Netlify。

# 將部落格部署到 Vercel

如果讀者像我一樣打算把 Monorepo 部署到 Vercel，那麼我們必須進行一些客製化的設定：

1. 設定 Local 專案

    首先準備 Build 指令：

    ```json title="personal-blog/package.json"
    {
      // ...
      "scripts": {
        // ...
        "vercel": "next build && next export"
      },
      // ...
    }
    ```

    由於我們使用 SSG 生成 html 網站內容，為了避免路徑參雜副檔名，可以建立 vercel 的設定檔如下：

    ```json title="personal-blog/vercel.json"
    {
      "cleanUrls": true
    }
    ```

2. 設定 Vercel 專案

    | 欄位路徑 | 內容 |
    | -- | -- |
    | `General`.`Root Directory` | `packages/personal-blog` |
    | `Build & Development Settings`.`Build Command` | 覆寫為 `yarn vercel` |
    | `Build & Development Settings`.`Output Directory` | 覆寫為 `out` |

    ## 避免非必要的部署 [^1] [^2]

    [^1]: [How do I use the "Ignored Build Step" field on Vercel?](https://vercel.com/guides/how-do-i-use-the-ignored-build-step-field-on-vercel)
    [^2]: [How to prevent unnecessary Vercel builds](https://www.raulmelo.dev/til/how-to-prevent-unnecessary-vercel-builds)

    如果你的 Monorepo 有超過一個可部署的專案，那麼就必須避免 A 專案的改動觸發 B 專案的部署。解決方式之一是偵測特定 package 內的檔案變動，如果有變動則進行部署，若無變動則忽略部署。

    進入到專案設定 -> 點選 `Git` -> 捲動至 `Ignored Build Step` 欄位，輸入：

    ```
    git diff --quiet HEAD^ HEAD .
    ```

    此處需要特別注意，偵測的路徑是 `.` 而不是 `./packages/personal-blog`，因為我們在第一步的設定中已經調整過根目錄了，所以此處的路徑是相對於根目錄而言。

# 將部落格部署到 Netlify

1. 設定 Local 專案

    除了準備 Build 指令以外，由於 Netlify 預設使用 npm，因此可以使用 `packageManager` 指定使用 yarn：

    ```json title="personal-blog/package.json"
    {
      // ...
      "packageManager": "yarn@1.22.19",
      "scripts": {
        // ...
        "netlify": "next build && next export"
      },
      // ...
    }
    ```

2. 設定 Netlify 專案

    | 欄位 | 內容 |
    | -- | -- |
    | Base directory | `./packages/personal-blog` |
    | Build command | `yarn netlify` |
    | Publish directory | `./packages/personal-blog/out` |

    Netlify 預設就會偵測 base directory 內的檔案變動來決定是否要執行部署[^3]，因此不用像 Vercel 一樣手動設定來避免非必要的部署。

    [^3]: [Ignore builds](https://docs.netlify.com/configure-builds/ignore-builds/)

部署


# MDX 語法

身為一位開發者，肯定對於 Markdown 不陌生，身為 React 的開發者，肯定也對 Component 不陌生，而 MDX 語法正是 Markdown 與 Component 兩者的結合，它允許我們在 Markdown 語法裡穿插 JSX 語法，這使得 Markdown 速記語法如虎添翼，讓文章可以變得更為豐富多彩，簡單、易用、高度彈性等眾多好處讓我毫無懸念地採用 MDX 作為撰寫文章的主要語法，例如我可以這樣子寫文章：

```md
# Work Experience

<Inline justifyContent="space-between" alignItems="center" gap="s" wrap="wrap">
## Senior Backend Engineer, [ĒSEN Inc.](https://www.linkedin.com/company/eseninc/)
*2022.03 - 2023.01*
</Inline>

- Kicked off both business-facing and customer-facing projects with microservice architecture and domaindriven design (DDD) pattern
- Implemented a reservation system with optimistic lock strategy to prevent double booking
- Implemented the design system Essence to modularize and accelerate frontend development
```

# Frontmatter 語法

慣例上使用 Markdown 撰寫部落格文章時都會搭配 `Frontmatter` 語法來補足細節設定，像是文章標題、摘要、發佈日期等，不是文章主體，卻又與文章相關的次要資訊。因此本站使用 MDX 時也應該支援 Frontmatter 語法，一般都是在檔案開頭使用 `---` 這個 fenced block 夾住 yaml 語法，然後才是 MDX 語法的內文，例如：

```md
---
title: 文章標題
publishDate: '2023-03-02'
keywords:
  - 關鍵字1
  - 關鍵字2
---

# Title

paragraph.
```

# 網站頁面 vs. 部落格文章

一個部落格除了文章以外，其實還會有站內的頁面，像是`關於網站`、`關於作者`、`作品集`等，他們也屬於作者所撰寫的內容，因此我希望這些網站頁面與部落格文章在撰寫時的體驗是一致的，都應該使用 MDX 語法來完成，差別在於網站頁面應遵守 Next.js 的檔案結構，而部落格文章則可以儲存於 Source Code 之外，所以我的檔案編排會是如以下所示結構：

```
personal-blog/
  - content/ <--- 部落格文章可以放在 pages 資料夾外
    - posts/
      - post1.mdx
      - post2.mdx
      - post3.mdx
      - ...
  - pages/ <--- 網站頁面遵循 Next.js 的路由規則
    - index.mdx
    - about-site.mdx
    - about-author.mdx
    - 404.js
    - ...
  - ...
```

# 渲染網站頁面

在 Next.js 官方文件 [Using MDX with Next.js](https://nextjs.org/docs/advanced-features/using-mdx) 當中已經有詳盡說明如何在你的專案使用 MDX，基本上照著操作就能順利渲染 `pages/*.mdx` 了，以下是我的設定方式：

1. 安裝相依

    ```shell
    yarn workspace @app/personal-blog add \
      @mdx-js/loader \
      @mdx-js/react \
      @next/mdx \
      remark-frontmatter \
      remark-gfm
    ```

2. 設定 `next.config`

    ```js title="personal-blog/next.config.mjs"
    import createMDXDecorator from '@next/mdx'
    import { getMdxOptions } from './utils/mdx.mjs'

    const withMDX = createMDXDecorator({
      extension: /\.mdx?$/,
      options: {
        ...getMdxOptions(),
        // If you use `MDXProvider`, uncomment the following line.
        providerImportSource: '@mdx-js/react',
      },
    })

    const nextConfig = {
      transpilePackages: ['@module/utils', '@module/essence'],
      reactStrictMode: true,
      pageExtensions: ['js', 'jsx', 'md', 'mdx'],
      // ...
    }

    export default withMDX(nextConfig)
    ```

    此處把 MDX 外掛的設定獨立出來，方便管理及重用：

    ```js title="personal-blog/utils/mdx.mjs"
    import remarkFrontmatter from 'remark-frontmatter'
    import remarkGfm from 'remark-gfm'

    export const getMdxOptions = () => {
      return {
        remarkPlugins: [
          remarkFrontmatter,
          remarkGfm,
        ],
        rehypePlugins: [],
      }
    }
    ```

3. 使用客製化元件

    如果想要客製化渲染 MDX 內容時使用的 Component，首先要準備一個客製元件對照表：

    ```js title="personal-blog/components/mdx/MDXComponents.js"
    import Text from '@module/essence/components/Text' // 使用來自 Design System 的元件

    const MDXComponents = {
      p: (props) => <Text {...props} />,
    }

    export default MDXComponents
    ```

    接下來可以在應用程式的最外層注入這些客製化元件：

    ```jsx title="personal-blog/pages/_app.js"
    import { MDXProvider } from '@mdx-js/react'
    import MDXComponents from '../components/mdx/MDXComponents'

    const MyApp = ({ Component, pageProps }) => {
      return (
        <MDXProvider components={MDXComponents}>
          <Component {...pageProps} />
        </MDXProvider>
      )
    }

    export default MyApp
    ```

    如果你的部落格可能需要支援多種風格的客製化元件，也可以考慮把 `MDXProvider` 放在 Layout Component：

    ```js title="personal-blog/components/layout/SitePageLayout.js"
    import { MDXProvider } from '@mdx-js/react'
    import Container from '@module/essence/components/Container'
    import MDXComponents from '../mdx/MDXComponents'

    export default ({ children, ...rest }) => {
      return (
        <Container fluid {...rest}>
          <MDXProvider components={MDXComponents}>{children}</MDXProvider>
        </Container>
      )
    }
    ```

    但是要記得在 MDX 頁面使用 `export` 來指定 Layout：

    ```md title="personal-blog/pages/example.mdx"
    import SitePageLayout from '../components/layout/SitePageLayout'
    export default ({ children }) => <SitePageLayout>{children}</SitePageLayout>

    # 標題一

    內文。
    ```

# 渲染部落格文章

接下來讓我們來看看如何渲染 Source Code 以外的 MDX 檔案。

1. 路由

    假設我們希望每篇文章的網址形式長成像是 `https://example.com/blog/some-awesome-slug` 這樣，那麼按照 Next.js 的標準使用方式，我們可以建立頁面 `pages/blog/[postSlug]/index.js` 來處理動態的 `postSlug`：

    ```jsx title="personal-blog/pages/blog/[postSlug]/index.js" highlightLines="11-15"
    import { getPosts } from '../../../utils/post' // 下文將會解釋

    const BlogPostPage = () => {
      // ...
      return 
    }

    export async function getStaticPaths() {
      const posts = getPosts()
      return {
        paths: posts.map(post => ({
          params: {
            postSlug: post.slug,
          },
        })),
        fallback: false, // can also be true or 'blocking'
      }
    }
    
    export default BlogPostPage
    ```

2. 渲染 MDX 內容

    這裡我使用了 `next-mdx-remote` 這個 Library 來輔助我把 MDX 文字渲染成 React 元件，所以首先安裝這個相依：

    ```shell
    yarn workspace @app/personal-blog add next-mdx-remote
    ```

    接著修改 `pages/blog/[postSlug]/index.js`，將 MDX 原始碼 `serialize` 之後傳遞給 `<MDXRemote />` 即可渲染出內容了：

    ```jsx title="personal-blog/pages/blog/[postSlug]/index.js" highlightLines="11,23-28"
    import Container from '@module/essence/components/Container'
    import { MDXRemote } from 'next-mdx-remote'
    import { serialize } from 'next-mdx-remote/serialize'
    import { getMdxOptions } from '../../../utils/mdx.mjs'
    import { getPostByPostSlug, getPosts } from '../../../utils/post' // 下文將會解釋

    const BlogPostPage = ({ post, mdxSource }) => {
      return (
        <Container fluid>
          <h1>{post.frontmatter.title}</h1>
          <MDXRemote {...mdxSource} components={MDXComponents} />
        </Container>
      )
    }

    export async function getStaticPaths() {
      // ...
    }

    export const getStaticProps = async ({ params }) => {
      const { postSlug } = params
      const post = getPostByPostSlug(postSlug)
      const mdxSource = await serialize(post.content, {
        mdxOptions: {
          ...getMdxOptions(),
          format: 'mdx',
        },
      })
      return {
        props: {
          post,
          mdxSource,
        },
      }
    }

    export default BlogPostPage
    ```

3. 使用 `fs` 讀取 MDX 原始內容

    在上方的程式碼中，我們使用到了兩個 utility functions `getPosts` 與 `getPostByPostSlug`，分別可以取得文章列表，以及根據 Slug 取得特定文章。這背後的實作其實只有單純地操作檔案系統，也因此我們的部落格文章儲存位置不必受限於 Next.js 的規範。
    
    處理 MDX 內容時會需要同時解析 Frontmatter，可以使用 `gray-matter` 這個 Library：

    ```shell
    yarn workspace @app/personal-blog add gray-matter
    ```

    我的 utility function 實作約略如下：

    ```js title="personal-blog/utils/post.js"
    import fs from 'fs'
    import matter from 'gray-matter'
    import path from 'path'

    class BlogPost {
      constructor(absoluteMDXFilePath) {
        this.absoluteFilePath = absoluteMDXFilePath
        this.parsedPath = path.parse(this.absoluteFilePath)
        this.fileContent = fs.readFileSync(this.absoluteFilePath, 'utf-8')
        const parsedFileContent = matter(this.fileContent)
        this.frontMatter = parsedFileContent.data
        this.slug =
          this.frontMatter.index?.partialSlug ||
          this.parsedPath.name.replace(/.mdx$/, '')
        this.content = parsedFileContent.content
      }

      toSerializable() {
        let serialized = {
          slug: this.slug,
          frontMatter: this.frontMatter,
          content: this.content,
        }
        return serialized
      }
    }

    export const getPosts = () => {
      const files = fs.readdirSync(path.join(process.cwd(), 'content/posts'), {
        withFileTypes: true,
      })
      const posts = files.map((file) => {
        let blogPost
        if (file.isDirectory()) {
          blogPost = new BlogPost(
            path.join(process.cwd(), 'content/posts', file.name, 'index.mdx')
          )
        } else {
          blogPost = new BlogPost(
            path.join(process.cwd(), 'content/posts', file.name)
          )
        }
        return blogPost.toSerializable()
      })
      return posts
    }

    export const getPostByPostSlug = (postSlug) => {
      const posts = getPosts()
      const post = posts.find((post) => post.slug === postSlug)
      return post
    }
    ```

    使用上需要特別注意，我們可能會使用 `getStaticProps` 來傳遞 post 的 instance 給 React Component，但是只有相容 JSON 的資料格式可以被傳遞，因此 `BlogPost` 提供了 `toSerializable()` 這個方法來處理 instance 的序列化。

文章內容管理


# 渲染文章索引列表

從前面的文章中，我們已經知道如何渲染一篇文章，接下來只要如法泡製，就能建立一個索引頁面列出部落格中所有的文章了。

```jsx title="personal-blog/pages/blog/index.js"
import Container from '@module/essence/components/Container'
import Heading from '@module/essence/components/Heading'
import { getPosts } from '../../utils/post'

const BlogPostIndexPage = ({ posts }) => {
  return (
    <Container>
      {posts.map((post) => (
        <Link key={post.slug} fluid href={`/blog/${post.slug}`}>
          <Heading size="m">{post.frontMatter.title}</Heading>
        </Link>
      ))}
    </Container>
  )
}

export const getStaticProps = ({ params }) => {
  return {
    props: {
      posts: getPosts()
    },
  }
}

export default BlogPostIndexPage
```

# 分頁處理

當文章數量不多時，或許唯一的索引頁面是一個可行的做法，但隨著部落格的經營，文章只會增加不會減少，如果文章數量達到某個規模時，勢必要採取某些方法讓這個索引頁面不要過度膨脹。目前這個階段，我傾向使用分頁來管理，因為對於讀者來說，仍然有辦法透過前往不同的分頁來瀏覽完所有文章。如果文章再成長到下一個規模時，或許就要捨棄分頁，改用關鍵字搜尋了，但分頁機制對於目前的部落格規模來說已經十分足夠！

我的實作方式是建立每一個分頁的路由頁面，並且擴充 utility functions 以支援分頁計算。

1. 路由

    ```jsx title="personal-blog/pages/blog/page/[pageId].js"
    import Container from '@module/essence/components/Container'
    import Heading from '@module/essence/components/Heading'
    import Label from '@module/essence/components/Label'
    import { getPosts, getPostsByPageSizeAndPageId } from '../../../utils/post'

    const BlogPostIndexPage = ({ posts, pagination }) => {
      return (
        <Container>
          {posts.map((post) => (
            <Link key={post.slug} fluid href={`/blog/${post.slug}`}>
              <Heading size="m">{post.frontMatter.title}</Heading>
            </Link>
          ))}
          <Label size="m">
            第{pagination.pageId}頁，共{pagination.pageCount}頁
          </Label>
        </Container>
      )
    }

    export async function getStaticPaths() {
      const BLOG_PAGE_SIZE = 10
      const posts = await getPosts()
      const pageCount = Math.ceil(posts.length / BLOG_PAGE_SIZE)
      return {
        paths: Array(pageCount)
          .fill(0)
          .map((_, pageIndex) => {
            const pageId = `${pageIndex + 1}`
            return {
              params: {
                pageId,
              },
            }
          }),
        fallback: false, // can also be true or 'blocking'
      }
    }

    export const getStaticProps = ({ params }) => {
      const BLOG_PAGE_SIZE = 10
      const posts = getPosts()
      const pageCount = Math.ceil(posts.length / BLOG_PAGE_SIZE)
      const { pageId } = params
      const currentPagedPosts = getPostsByPageSizeAndPageId(BLOG_PAGE_SIZE, pageId)
      return {
        props: {
          posts: currentPagedPosts,
          pagination: {
            pageSize: BLOG_PAGE_SIZE,
            pageCount,
            pageId,
          },
        },
      }
    }

    export default BlogPostIndexPage
    ```

2. 分頁計算 utility functions

    只要能夠知道所有文章的數量，以及每頁文章數量，就能進行分頁計算，或是拿到屬於特定頁面的文章列表，此外，我還打算使用文章發佈日期進行排序。因此我們可以在 utility functions 實作 `getSortedPosts` 與 `getPostsByPageSizeAndPageId` 兩個函數：

    ```js title="personal-blog/utils/post.js"
    export const getPosts = () => {
      // ...
    }

    export const getSortedPosts = () => {
      const posts = getPosts()
      const sortedPosts = posts.sort((a, b) => {
        if (a.frontMatter.publishDate < b.frontMatter.publishDate) {
          return 1
        } else if (a.frontMatter.publishDate > b.frontMatter.publishDate) {
          return -1
        } else {
          return 0
        }
      })
      return sortedPosts
    }

    export const getPostsByPageSizeAndPageId = (pageSize, pageId) => {
      const sortedPosts = getSortedPosts()
      const offset = pageSize * (parseInt(pageId) - 1)
      return sortedPosts.slice(offset, offset + pageSize)
    }
    ```

如此一來，我們基本上已經滿足一個部落格所需要的最低功能了：
- 編輯者可以撰寫 MDX 文章檔案
- 讀者可以瀏覽具有分頁的文章列表
- 讀者可以點選特定文章並且瀏覽全文

相信讀者們也已具備足夠的知識，可以開始動手客製出自己的部落格，展開屬於自己的旅程了！關於功能性的講解在此先告一段落，後續文章將會開始介紹偏向營運層面以及閱讀體驗的功能，歡迎有興趣繼續鑽研的朋友一起看下去。

文章索引及分頁


# Sitemap

Sitemap 是提供搜尋引擎讀取站內頁面清單的常見方式，可以加速搜尋引擎幫我們的網站建立索引，而網站主需要做的事情就是在根目錄提供 `sitemap.xml` 檔案，檔案內容也需遵循 Sitemap 規範。

在 Next.js 的專案中，我們可以手動建立 `/public/sitemap.xml`、手動填入 xml，並以靜態檔案的方式部署。然而，每當我們的部落格新增或刪除文章時，就必須要手動更新 `sitemap.xml`，這顯然會造成管理上的困擾。為了解決這個問題，我的做法是取巧地建立一個空白頁面，但是在 `getStaticProps()` 裡渲染並輸出 `sitemap.xml`：

```js title="personal-blog/pages/generateSitemap.js"
import { writeToPublic } from '../utils/output'
import { getPosts } from '../utils/post'
import { generateSiteMapInXML } from '../utils/seo'

export default () => {}

export const getStaticProps = async () => {
  const posts = getPosts()
  const sitemap = generateSiteMapInXML(posts)
  writeToPublic('sitemap.xml', sitemap)
  return {
    props: {},
  }
}
```

此處獨立出 Utility function `writeToPublic`，負責把檔案寫入 `/public` 資料夾：

```js title="personal-blog/utils/output.js"
import fs from 'fs'
import path from 'path'

export const writeToPublic = (relativeFilePath, fileContent) => {
  const absoluteFilePath = path.join(process.cwd(), 'public', relativeFilePath)
  fs.writeFileSync(absoluteFilePath, fileContent)
}
```

Sitemap 檔案內容的渲染過程也獨立於 utility function `generateSiteMapInXML`：

```js title="personal-blog/utils/seo.js"
export const generateSiteMapInXML = (posts) => {
  return `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    ${posts
      .map(
        (post) => `
  <url>
    <loc>{`https://example.com/blog/${post.slug}`}</loc>
    <lastmod>${post.lastModifiedTime}</lastmod>
  </url>`
      )
      .join('')}
</urlset>`
}
```

最後記得把這一份建置檔案列入 gitignore：

```txt title="personal-blog/.gitignore"
/public/sitemap.xml
```

# 伺服器端渲染 (SSR, Server Side Rendering)

要讓搜尋引擎能夠理解我們的網站內容，除了使用 Sitemap 編列頁面索引以外，每一個獨立頁面也都要能夠支援伺服器端渲染（SSR），這樣子爬蟲程式讀取頁面時才能夠拿到結構化的 Html 及頁面內容，而不是拿到需要被 Evaluate 的 Javascript。不過，Next.js 原生就已經支援 SSR 了，我們不必做任何處理就能享有 SSR 的效果，SSG 的過程也可以直接使用 SSR 產生的內容。

雖然對於爬蟲程式而言我們不用做任何努力，但是部落格的佈景主題、客製化元件等都是延遲載入 CSS，對於真人閱讀者而言，將會先看到 SSR 產生的 HTML，等到 CSS 被載入之後才套用設計過的佈景主題，這段載入 CSS 的時間差會造成閱讀者看到頁面閃爍、抖動、跳躍而影響閱讀體驗，為了讀者的眼睛著想，我的解法是把 CSS 納入 SSR 的過程當中。

由於我的 Design System 和各種調整樣式的處理方式都是透過 `styled-components` 來完成，所以只要替 styled-components 設定 SSR 即可，參考 [How to Set up Styled-Components with SSR in NextJS (Typescript)](https://reacthustle.com/blog/nextjs-styled-components-ssr-typescript) 一文之後，兩個步驟就能搞定：

1. 調整 Next Config

    ```js title="personal-blog/next.config.mjs" highlightLines="3-5"
    const nextConfig = {
      // ...
      compiler: {
        styledComponents: true,
      },
    }

    export default withMDX(nextConfig)
    ```

2. 更新 `_document.js`

    ```jsx title="personal-blog/pages/_document.js"
    import Document, { Head, Html, Main, NextScript } from 'next/document'
    import { ServerStyleSheet } from 'styled-components'

    class MyDocument extends Document {
      static async getInitialProps(ctx) {
        const sheet = new ServerStyleSheet()
        const originalRenderPage = ctx.renderPage
        try {
          ctx.renderPage = () =>
            originalRenderPage({
              enhanceApp: (App) => (props) =>
                sheet.collectStyles(<App {...props} />), //gets the styles from all the components inside <App>
            })
          const initialProps = await Document.getInitialProps(ctx)
          return {
            ...initialProps,
            styles: (
              <>
                {initialProps.styles}
                {sheet.getStyleElement()}
              </>
            ),
          }
        } finally {
          sheet.seal()
        }
      }

      render() {
        return (
          <Html>
            <Head />
            <body>
              <Main />
              <NextScript />
            </body>
          </Html>
        )
      }
    }

    export default MyDocument
    ```

# JSON-LD

JSON-LD 是一種結構化語法，用來描述網站的型態及內容，搜尋引擎也會針對帶有 JSON-LD 的網頁呈現特化的搜尋結果排版。使用方式其實就是在網頁裡插入 `<script />` 標籤，而內容只要依照 [Schema.org](https://schema.org/) 的規範填寫即可。

我的實作是撰寫專用的 SEO 元件，並且在文章頁面插入該元件：

```jsx title="personal-blog/components/utility/SEO.js"
import Head from 'next/head'
import { generateJsonLdForPost } from '../../utils/seo'

export default ({ post }) => {
  return (
    <Head>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: generateJsonLdForPost(post),
        }}
        key="product-jsonld"
      />
    </Head>
  )
}
```

並且搭配 utility function 來產生 JSON-LD 內容：

```js title="personal-blog/utils/seo.js"
export const generateJsonLdForPost = (post) => {
  const { HOST, SITE_NAME, AUTHOR_NAME } = getConfig()
  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'BlogPosting',
    headline: post.frontMatter.title,
    genre: ['SEO', 'JSON-LD'],
    keywords: post.frontMatter?.keywords || [],
    url: getUrl(HOST, post),
    datePublished: post.frontMatter.publishDate,
    dateCreated: post.frontMatter.publishDate,
    dateModified: post.lastModifiedTime,
    articleBody: post.content,
    publisher: {
      '@type': 'Organization',
      name: SITE_NAME,
      url: HOST,
      logo: {
        '@type': 'ImageObject',
        url: `${HOST}/site/favicon.svg`,
      },
    },
    author: {
      '@type': 'Person',
      name: AUTHOR_NAME,
      url: HOST,
    },
    creator: {
      '@type': 'Person',
      name: AUTHOR_NAME,
    },
    mainEntityOfPage: {
      '@type': 'WebPage',
      '@id': `${HOST}/blog`,
    },
  }
  if (post.frontMatter.hero) {
    jsonLd.image = `${HOST}${post.frontMatter.hero.src}`
  }
  if (post.frontMatter.excerpt) {
    jsonLd.description = post.frontMatter.excerpt
  }
  return JSON.stringify(jsonLd)
}
```

## 測試 JSON-LD

如果想要驗證自己的 JSON-LD 是否正確，可以參閱 Google 的文件「[測試結構化資料](https://developers.google.com/search/docs/appearance/structured-data)」。

SEO 搜尋引擎最佳化

伺服器端渲染 (SSR, Server Side Rendering)


多年以來，我一直想要有一個既能專注於寫作，又能高度客製化文章視覺的部落格系統，過去雖嘗試過 Blogger, Wordpress, Self-hosting, Hexo, Gatsby, Medium, Vocus 等方法，但每個平台終究會遇到難以應付的不便利之處，服務倒閉、文章搬遷困難、不支援 Markdown 語法、免費額度限制、被分潤機制強迫吸血，以上種種困難使我長久無法找到心目中理想的方案。

幸運的是，近年來前端生態蓬勃發展，React.js 及 Next.js 的誕生與演進讓自建部落格的門檻大幅下降，加上工作上的經驗累積，我已有足夠的能力從頭開發屬於自己的部落格，開發過程中關鍵的決策、思路、實作細節都將收錄在本系列文章當中。

使用 Next.js 手把手建立自己的部落格


在每一篇文章的開頭，我們都應該撰寫 Frontmatter，如此才能標記這篇文章的屬性。

```plaintext
---
index:
  skip: true
  partialSlug: awesome-post
hero:
  src: /posts/awesome-post/hero.jpg
  backdrop: false
  fadedEdge: true
title: 主文章
excerpt: 內文摘要
toc:
  isDisabled: false
publishDate: '1970-01-01'
tags:
  - WIP
  - Early Release
  - variant: negative
    children: 18+
keywords:
  - keyword1
  - keyword2
collections:
  - ./my-awesome-post-1.mdx
  - ./my-awesome-post-2.mdx
remark: 不想被看見的文章相關資料
---
此處開始即為 MDX 內文
```

## 屬性繼承

如果您的文章使用了 `collections`，那麼子文章將會受父文章影響而產生以下副作用：

1. 子文章的 `slug` 將會隱性地前綴父文章的 `slug`
2. 子文章的 `keywords` 將會隱性地後綴父文章的 `keywords`

使用 Frontmatter


# 一級標題

## 二級標題

### 三級標題

#### 四級標題

##### 五級標題

###### 六級標題

# 文章

修光接物認味老幾化教全為展現不也不基車部……去出我社性有陽。的了國人吸母……只動此和邊才提最呢的問布跟，是持思必點背演要事時地現保服可於感，也生少早。有不的素體神可話北智元羅我！子康相來用治世是人多重情們定區麼北歌車政對民美決一起過發經輕前解久神、趣她冷利我我，作以其習人兒片到居也樣夜為修的而一人人天在景關大有靈能慢念件，考石大不、取話整麼車；鄉己北的家公家的麗是白元評公化麼的。目好絕河理……實出變生且馬媽流，福備流中間，求夠是，最打有王很一無進步將打低果果獲了多；只不情具想定下開我落人本少最。所理親進電：看思才後！經對以經意當。

一美位市銀使立人似他對考們方傳工友變？個花連老程。式部部氣意、動有所在：出不新出教大中時臉是我會實和較，裡必住水房本光分主，人要要無者手王化小他法學女晚小就幾們片些開各期來自了時而，買當沒工的低他幾為在：生發息觀花港他意家。

望廠念我雜藝市岸；助別司國上房兩要媽臺空完起示整面國面所當。

破十他麼的快。對急一資、名來前對？為這個著天傳。引想務樹面行是得很：就分易……小有中當後社的我顯外方樂前中？資有師不黑把部險一紅。體的問場去的所情點度，從片它科值明應；製是手色。名居望，不放音目生！是成法保面何了生要得教雖獲。卻走思星通天是是、公球氣小是。

行論會風些聲的上行謝？

**粗體**，_斜體_，~~刪除線~~

# 超連結

文章內插入的[超連結](/blog/sample-mdx-collection/)長這樣。（此連結會回到主文章）

# 水平線

在文章原始碼內輸入`---`、`___`或`***`即可產生水平線：

---

# 引用

> 我思故我在

> Most good programmers do programming not because they expect to get paid or get adulation by the public, but because it is fun to program.

> 我思故我在
> <cite>- 法國哲學家笛卡爾</cite>

> Most good programmers do programming not because they expect to get paid or get adulation by the public, but because it is fun to program.
> <cite>- Linus Torvalds</cite>

# 清單

## 有序清單

1. 甲
   1. 甲上
   2. 甲下
1. 乙
1. 丙

## 無序清單

- 甲
- 乙
  - 乙上
  - 乙下
- 丙

# 上下標

- 19<sup>th</sup> (使用 html 產生)
- H<sub>2</sub>O (使用 html 產生)

# 註腳

您可以在文字中插入註腳[^footnote]，使文章的排版[^typography]更加整齊且有秩序，適時增添學術導向的風采。

[^footnote]: **腳註**

    又名註腳、筆記、札記（德語：Fußnote；英語：Footnote），是讀書所做的筆錄、見解、體會、看法、觀點、心得、感想的總稱。

[^typography]: 排版，在固定版面內擺置各種不同型態的資料。

# 縮寫

<abbr title="請求意見稿（英語：Request for Comments，縮寫：RFC），又翻譯作意見徵求，意見請求，請求評論是由網際網路工程任務組（IETF）發布的一系列備忘錄。">RFC</abbr> 和 <abbr title="網際網路工程任務組（英語：Internet Engineering Task Force，縮寫：IETF）是一個開放的標準組織，負責開發和推廣自願網際網路標準（Internet Standard，英文縮寫為 STD），特別是構成 TCP/IP 協定族（TCP/IP）的標準。">IETF</abbr> 都是軟體界很常聽見的詞彙。

# 定義

CAP

: 在理論計算機科學中，CAP 定理（CAP theorem），又被稱作布魯爾定理（Brewer's theorem），它指出對於一個分布式計算系統來說，不可能同時滿足以下三點： 1. 一致性（Consistency） （等同於所有節點訪問同一份最新的數據副本） 2. 可用性（Availability）（每次請求都能獲取到非錯的響應——但是不保證獲取的數據為最新數據） 3. 分區容錯性（Partition tolerance）（以實際效果而言，分區相當於對通信的時限要求。系統如果不能在時限內達成數據一致性，就意味著發生了分區的情況，必須就當前操作在 C 和 A 之間做出選擇。）

ACID

: 是指資料庫管理系統（DBMS）在寫入或更新資料的過程中，為保證事務（transaction）是正確可靠的，所必須具備的四個特性：原子性（`atomicity`，或稱不可分割性）、一致性（`consistency`）、隔離性（`isolation`，又稱獨立性）、持久性（`durability`）。


文字排版

使用表情符號


原始碼內圖片：

![minion](/posts/betterlog-manual/minion.png "這是minion")

網路圖片：

![Stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg "The Stormtroopocat")

![狗狗](https://picsum.photos/id/237/200/300)

使用圖片


# 一般表格

| 欄位一 | 欄位二 |
| ----- | ------ |
| 內容  | 內容    |

# 置右

| 欄位一 | 欄位二 |
| -----:| -----:|
| 內容  | 內容   |

# 大表格

| 欄位1 | 欄位2 | 欄位3 | 欄位4 | 欄位5 | 欄位6 | 欄位7 | 欄位8 | 欄位9 | 欄位10 | 欄位11 | 欄位12 | 欄位13 | 欄位14 | 欄位15 | 欄位16 | 欄位17 | 欄位18 | 欄位19 | 欄位20 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |
| 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 | 內容 |


使用表格


# 快速上手

## 行內高亮

這是一個`行內`的`高亮`範例。The `inline code` could be an English term.

## 區塊高亮

只要使用標準的 Markdown Fenced Code Block 語法，搭配語言名稱，即可產生高亮過的視覺呈現。

- JSX語法

  ```jsx
  import React from 'react'
  import Typography from '@material-ui/core/Typography'
  import Layout from '../components/layout'
  import SEO from '../components/seo'

  const AboutPage = () => (
    <Layout>
      <SEO title="筆者" />
      <Typography variant="h4">
        筆者
      </Typography>
    </Layout>
  )

  export default AboutPage
  ```

- Diff 語法

  ```diff
  obj = {
    k1: 'v1',
  - k2: 'v2',
  - k2_1: 'v2_1',
  + k3: 'v3',
  + k3_1: 'v3_1',
    k4: 'v4',
  };
  ```

當內容過長時，高亮區塊會自動套用卷軸：

```
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
```

# 進階使用區塊高亮

## 行號

如果程式碼行數很多，可以搭配 `showLineNumbers` 屬性啟用行號功能：

```jsx showLineNumbers
import React from 'react'
import Typography from '@material-ui/core/Typography'
import Layout from '../components/layout'
import SEO from '../components/seo'

const AboutPage = () => (
  <Layout>
    <SEO title="筆者" />
    <Typography variant="h4">
      筆者
    </Typography>
  </Layout>
)

export default AboutPage
```

## 強調特定範圍

無論顯示行號與否，皆可以使用 `highlightLines="2,9-11"` 等語法來強調特定的程式碼範圍：

```jsx highlightLines="2,9-11"
import React from 'react'
import Typography from '@material-ui/core/Typography'
import Layout from '../components/layout'
import SEO from '../components/seo'

const AboutPage = () => (
  <Layout>
    <SEO title="筆者" />
    <Typography variant="h4">
      筆者
    </Typography>
  </Layout>
)

export default AboutPage
```

顯示行號搭配強調範圍：

```python showLineNumbers highlightLines="1,20"
class Solution:
    def longestCommonPrefix(self, strs):
        if len(strs) == 0:
            return ''
        elif len(strs) == 1:
            return strs[0]
        min_len = min(*[len(s) for s in strs])

        i = 0
        while i < min_len:
            for j in range(1, len(strs)):
                if strs[j][i] != strs[0][i]:
                    return strs[0][:i]
            i += 1
        if i == min_len:
            return strs[0][:min_len]
        return ''

s = Solution()
print(s.longestCommonPrefix(['a', 'ab']))
```

## 標題

`title` 屬性可用於輔助說明程式碼：

```python title="LeetCode 783. Minimum Distance Between BST Nodes"
class Solution:
    def minDiffInBST(self, root: Optional[TreeNode]) -> int:
        self.ans = float('inf')
        self.prev_val = -float('inf')
        def dfs(node):
            if node is None:
                return
            dfs(node.left)
            self.ans = min(self.ans, node.val - self.prev_val)
            self.prev_val = node.val
            dfs(node.right)
        dfs(root)
        return self.ans
```

或是提示檔案路徑及名稱：

```text title="public/robots.txt" showLineNumbers
User-agent: *
Disallow:
  
Sitemap: https://gocreating.lation.app/sitemap.xml
```

## REPL 模式

### 快速使用

您可以透過 `replEnabled` 屬性使區塊高亮看起來像是 Repl 操作介面：
  
```shell replEnabled
ls
cat a.txt
```

如果高亮區域包含了範例輸出，可以搭配 `replOptions.commandGroupLines` 屬性來指定指令範圍：

```shell replEnabled replOptions={{commandGroupLines: "1,4"}}
ls
a.txt
b.txt
cat a.txt
hello world
```

含有斷行的指令會根據 `replOptions.commandGroupLines` 的填寫結構自動辨識：

```shell replEnabled replOptions={{commandGroupLines: "1-3"}}
ls \
-a \
-l
total 2
-rw-r--r--     1 root  staff      43 Jan 12 14:16 a.txt
-rw-r--r--     1 root  staff    1743 Feb 16 12:09 b.txt
```

### 客製化 Prompt

`replOptions` 保留了許多客製化的彈性，請見範例：

- Node.js
  
  ```shell replEnabled replOptions={{prompt: ">", continuationPrompt: "...", commandGroupLines: "1,4-6"}}
  node
  Welcome to Node.js v16.14.2.
  Type ".help" for more information.
  0.2 + (
    3 / 5
  )
  0.8
  ```

- MySQL
  
  ```shell replEnabled replOptions={{prompt: "mysql>", continuationPrompt: "->", commandGroupLines: "1,2,4-7"}}
  set @my_var = 'foo';
  set @my_other_var = 'bar';

  CREATE TABLE people (
    first_name VARCHAR(30) NOT NULL,
    last_name VARCHAR(30) NOT NULL
  );
  Query OK, 0 rows affected (0.09 sec)
  ```

- PowerShell
  
  ```shell showLineNumbers highlightLines="1-4,6" replEnabled replOptions={{prompt: "ps c:\u005Cusers\u005Cgocreating>", continuationPrompt: ">>", commandGroupLines: "1-4,6"}}
  Write-Host `
  'Hello' `
  'from' `
  'PowerShell!'
  Hello from PowerShell!
  Write-Host 'Goodbye from PowerShell!'
  Goodbye from PowerShell!
  ```

### 跳脫字元

如果你的 `replOptions` 必須使用到 mdx 的保留字元，為了避免頁面渲染失敗，可以使用 Javascript Expression 來替換該字元。

```jsx
replOptions={{ prompt: "backslash " + String.fromCharCode(92) }}
replOptions={{ prompt: "backslash \u005C" }}
```

嵌入程式碼


畢氏定理可以用一個簡單的公式來表示：

$$
a^2 + b^2 = c^2
$$

其中 $a,b$ 代表直角三角形的短邊邊長，$c$ 代表最長邊邊長。


嵌入數學表示


BetterLog 支援撰寫 `PlantUML` 格式的 `CodeBlock`，該原始碼將會被編碼後置換成圖片。

```plantuml
class SimplePlantUMLPlugin {
    + transform(syntaxTree: AST): AST
}
```

```plantuml
@startuml
participant Participant as Foo
actor       Actor       as Foo1
boundary    Boundary    as Foo2
control     Control     as Foo3
entity      Entity      as Foo4
database    Database    as Foo5
collections Collections as Foo6
queue       Queue       as Foo7
Foo -> Foo1 : To actor 
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7: To queue
@enduml
```


使用 PlantUML


在 MDX 引擎的輔助下，我們可以在文章內撰寫 Javascript expression，例如：

1 + 2 = {1 + 2}
0.1 + 0.2 = {0.1 + 0.2}（如實呈現浮點數誤差）

也可以在文章內使用全域元件：

<Button variant="positive" onClick={() => { alert("Nice") }}>Click Me</Button>

撰寫 Expression 或是嵌入 React 元件


__Advertisement :)__

- __[pica](https://nodeca.github.io/pica/demo/)__ - high quality and fast image
  resize in browser.
- __[babelfish](https://github.com/nodeca/babelfish/)__ - developer friendly
  i18n with plurals support and easy syntax.

You will like those projects!

---

# h1 Heading 8-)
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading


## Horizontal Rules

___

---

***


## Typographic replacements

Enable typographer option to see result.

(c) (C) (r) (R) (tm) (TM) (p) (P) +-

test.. test... test..... test?..... test!....

!!!!!! ???? ,,  -- ---

"Smartypants, double quotes" and 'single quotes'


## Emphasis

**This is bold text**

__This is bold text__

*This is italic text*

_This is italic text_

~~Strikethrough~~


## Blockquotes


> Blockquotes can also be nested...
>> ...by using additional greater-than signs right next to each other...
> > > ...or with spaces between arrows.


## Lists

Unordered

+ Create a list by starting a line with `+`, `-`, or `*`
+ Sub-lists are made by indenting 2 spaces:
  - Marker character change forces new list start:
    * Ac tristique libero volutpat at
    + Facilisis in pretium nisl aliquet
    - Nulla volutpat aliquam velit
+ Very easy!

Ordered

1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit
3. Integer molestie lorem at massa


1. You can use sequential numbers...
1. ...or keep all the numbers as `1.`

Start numbering with offset:

57. foo
1. bar


## Code

Inline `code`

Indented code

    // Some comments
    line 1 of code
    line 2 of code
    line 3 of code


Block code "fences"

```plaintext
Sample text here...
```

Syntax highlighting

``` js
var foo = function (bar) {
  return bar++;
};

console.log(foo(5));
```

## Tables

| Option | Description |
| ------ | ----------- |
| data   | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext    | extension to be used for dest files. |

Right aligned columns

| Option | Description |
| ------:| -----------:|
| data   | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext    | extension to be used for dest files. |


## Links

[link text](http://dev.nodeca.com)

[link with title](http://nodeca.github.io/pica/demo/ "title text!")

Autoconverted link https://github.com/nodeca/pica (enable linkify to see)


## Images

![Minion](https://octodex.github.com/images/minion.png)
![Stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg "The Stormtroopocat")

Like links, Images also have a footnote style syntax

![Alt text][id]

With a reference later in the document defining the URL location:

[id]: https://octodex.github.com/images/dojocat.jpg  "The Dojocat"


## Plugins

The killer feature of `markdown-it` is very effective support of
[syntax plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin).


### [Emojies](https://github.com/markdown-it/markdown-it-emoji)

> Classic markup: :wink: :crush: :cry: :tear: :laughing: :yum:
>
> Shortcuts (emoticons): :-) :-( 8-) ;)

see [how to change output](https://github.com/markdown-it/markdown-it-emoji#change-output) with twemoji.


### [Subscript](https://github.com/markdown-it/markdown-it-sub) / [Superscript](https://github.com/markdown-it/markdown-it-sup)

- 19^th^
- H~2~O


### [Footnotes](https://github.com/markdown-it/markdown-it-footnote)

Footnote 1 link[^first].

Footnote 2 link[^second].

Inline footnote^[Text of inline footnote] definition.

Duplicated footnote reference[^second].

[^first]: Footnote **can have markup**

    and multiple paragraphs.

[^second]: Footnote text.


### [Definition lists](https://github.com/markdown-it/markdown-it-deflist)

Term 1

:   Definition 1
with lazy continuation.

Term 2 with *inline markup*

:   Definition 2

    \{ some code, part of Definition 2 \}

    Third paragraph of definition 2.

_Compact style:_

Term 1
  ~ Definition 1

Term 2
  ~ Definition 2a
  ~ Definition 2b


### [Abbreviations](https://github.com/markdown-it/markdown-it-abbr)

This is HTML abbreviation example.

It converts "HTML", but keep intact partial entries like "xxxHTMLyyy" and so on.

*[HTML]: Hyper Text Markup Language

### [Custom containers](https://github.com/markdown-it/markdown-it-container)

::: warning
*here be dragons*
:::


English Post Demo


此系列文章列舉了所有 BetterLog 目前版本所支援的語法，可供撰寫文章時作為參考。

BetterLog 使用說明書


# Query[^1]

[^1]: [Designing Queries (Human-Computer Interaction)](https://www.w3computing.com/systemsanalysis/designing-queries-human-computer-interaction/)

查詢通常會涉及三個主體：**E**ntity, **A**ttribute, **V**alue，如果將這三者類比到關聯式資料庫的話則分別是 Table, Column, Record，下表舉三個最基本的查詢為例：

| Notation   | Example |
| ---------- | --- |
| V ← (E, A) | 查詢保單的生效日 |
| E ← (A, V) | 查詢車牌號碼等於5566的保單 |
| A ← (E, V) | 查詢 A, B, C, ... 等保單屬性中 display 為 True 者 |

# Query Language

如果存在一套 Query Language 可以表達所有種類的 Query，則可稱此 Query Language 具有完備性（Query Complete）。

> 討論程式語言的可計算性時，經常會使用圖靈完備性[^2]（Turing Completeness）來描述某程式語言是否能夠表達所有種類的運算，因此本文借用相同概念延伸至 Query Language。

[^2]: https://zh.wikipedia.org/wiki/圖靈完備性

如果我們把所有種類的 Query 視為 Entity, Attribute, Value 與 CRUD 四大操作的排列組合，便能粗略地歸納 Query Language 的完備性，下表舉 MongoDB Query Language（MQL）及 GraphQL 為例：

| Query Completeness | MQL                | GraphQL             |
| ------------------ | ------------------ | ------------------- |
| Create Entity      | :heavy_check_mark: | :heavy_check_mark:  |
| Read Entity        | :heavy_check_mark: | :heavy_check_mark:  |
| Update Entity      | :heavy_check_mark: | :heavy_check_mark:  |
| Delete Entity      | :heavy_check_mark: | :heavy_check_mark:  |
| Create Attribute   | :heavy_check_mark: | :heavy_check_mark:  |
| Read Attribute     | :heavy_check_mark: | :heavy_check_mark:  |
| Update Attribute   | :heavy_check_mark: | :heavy_check_mark:  |
| Delete Attribute   | :heavy_check_mark: | :heavy_check_mark:  |
| Create Value       | :heavy_check_mark: | :heavy_check_mark:  |
| Read Value         | :heavy_check_mark: | :heavy_check_mark:  |
| Update Value       | :heavy_check_mark: | :heavy_check_mark:  |
| Delete Value       | :heavy_check_mark: | :heavy_check_mark:  |

# Completeness & Incompleteness

筆者之所以有機會撰寫此文，是因為 OneDegree 的產品之一 `IXT` 近期需要開發一套強而有力的搜尋引擎，就姑且稱做 `Advanced Filter` 吧！然而系統現存的 Legacy API 形式（下稱 `Internal API`）不夠完備，因此已無法滿足最新的需求了。

## The Incompleteness of Internal API

讓我們以車險為例子，具體來說，假設系統中存在兩張車險保單（Policy），其中被保標的（InsuredSubject）分別具有不同的屬性（ExtraDataAttributeValue）：

```python
policy_1 = Policy(
  insured_subjects=[
    InsuredSubject(
      extra_data_attribute_values=[
        ExtraDataAttributeValue(
          attribute_name='car_age',
          numeric_value=10
        ),
        ExtraDataAttributeValue(
          attribute_name='car_vendor',
          string_value='BMW'
        )
      ]
    )
  ]
)
policy_2 = Policy(
  insured_subjects=[
    InsuredSubject(
      extra_data_attribute_values=[
        ExtraDataAttributeValue(
          attribute_name='car_age',
          numeric_value=10
        ),
        ExtraDataAttributeValue(
          attribute_name='car_plate',
          string_value='OD5566'
        )
      ]
    )
  ]
)
```

當後台人員在 Advanced Filter 搜尋 `車齡 = 10` 且 `車牌 = OD5566` 的保單時，我們應該預期只會搜尋出 `policy_2`，且可能嘗試寫出類似以下的 Internal API Query：

```
GET /policies?fields=...&filter={
  "and": [
    {
      "and": [
        {"==": ["insured_subjects.extra_data_attribute_values.attribute_name", "car_age"]},
        {"==": ["insured_subjects.extra_data_attribute_values.numeric_value", 10]}
      ]
    },
    {
    "and": [
        {"==": ["insured_subjects.extra_data_attribute_values.attribute_name", "car_plate"]},
        {"==": ["insured_subjects.extra_data_attribute_values.string_value", "OD5566"]}
      ]
    }
  ]
}
```

你將發現其實外層的 `and` 運算元應該換成 `intersect`，或是內層遇到複數欄位時應該要能進行逐項匹配的運算，如此才能得到預期的搜尋結果。但是 Internal API 此時此刻並沒有上述的功能，因此可知 Internal API 在 Advanced Filter 所需的功能上並不完備。

## The Completeness of MQL

如果將同樣的情況重現於 MongoDB：

```
db.policy.insertMany([
  {
    "name": "policy_1",
    "insured_subjects": [
      {
        "extra_data_attribute_values": [
          {
            "attribute_name": "car_age",
            "numeric_value": 10
          },
          {
            "attribute_name": "car_vendor",
            "string_value": "BMW"
          }
        ]
      }
    ]
  }, {
    "name": "policy_2",
    "insured_subjects": [
      {
        "extra_data_attribute_values": [
          {
            "attribute_name": "car_age",
            "numeric_value": 10
          },
          {
            "attribute_name": "car_plate",
            "string_value": "OD5566"
          }
        ]
      }
    ]
  }
])
```

你將發現可以透過以下 MQL 實現理想中的查詢：

```
db.policy.find({
  "insured_subjects": {
    $elemMatch: {
      "extra_data_attribute_values": {
        $all: [
          {
            $elemMatch: {
              "attribute_name": "car_age",
              "numeric_value": 10
            }
          },
          {
            $elemMatch: {
              "attribute_name": "car_plate",
              "string_value": "OD5566"
            }
          }
        ]
      }
    }
  }
})
```

由於 MQL 在複數欄位上提供了 `$elemMatch` 運算元讓我們能夠進行逐項匹配的運算，使得最終結果是正確的，因此可知 MQL 在 Advanced Filter 所需的功能上是完備的。

## The Completeness of SQL

接著再看同樣的情況重現於關聯式資料庫，以 SQLAlchemy 的 ORM Query 為例：

```python
policy_query_1 = session\
  .query(Policy.id, Policy.number)\
  .join(Policy.insured_subjects)\
  .join(InsuredSubject.extra_data_attribute_values)\
  .filter(
    and_(
      InsuredSubjectExtraDataAttributeValue.attribute_name == 'car_age',
      InsuredSubjectExtraDataAttributeValue.numeric_value == 10,
    )
  )
policy_query_2 = session\
  .query(Policy.id, Policy.number)\
  .join(Policy.insured_subjects)\
  .join(InsuredSubject.extra_data_attribute_values)\
  .filter(
    and_(
      InsuredSubjectExtraDataAttributeValue.attribute_name == 'car_plate',
      InsuredSubjectExtraDataAttributeValue.string_value == 'OD5566',
    )
  )
policies = policy_query_1.intersect(policy_query_2).all()
```

聰明的你應該已經知道，由於 SQL 提供了 `INTERSECT` 語句使得查詢結果符合預期，因此可知 SQL 在 Advanced Filter 所需的功能上也是完備的。

# OneDegree Query Language

考量翻修 Internal API 的巨大成本，最終與各方 Stakeholders 協議發展新的 Query 方式（下稱 ODQL），最低要求除了要滿足 Advanced Filter 的需求外，ODQL 也必須涵蓋 Internal API 既有的所有功能，並且最好順便補足先前 Internal API 曾經遇過的痛點。

## Completeness

就 Advanced Filter 所需的完備性而言，ODQL 僅需完成 Read Only 的部分，暫時無須考量 Create, Update 及 Delete 的操作：

| Query Completeness | MQL                | GraphQL             | ODQL                |
| ------------------ | ------------------ | ------------------- | ------------------- |
| Create Entity      | :heavy_check_mark: | :heavy_check_mark:  | :x:                 |
| Read Entity        | :heavy_check_mark: | :heavy_check_mark:  | :heavy_check_mark:  |
| Update Entity      | :heavy_check_mark: | :heavy_check_mark:  | :x:                 |
| Delete Entity      | :heavy_check_mark: | :heavy_check_mark:  | :x:                 |
| Create Attribute   | :heavy_check_mark: | :heavy_check_mark:  | :x:                 |
| Read Attribute     | :heavy_check_mark: | :heavy_check_mark:  | :heavy_check_mark:  |
| Update Attribute   | :heavy_check_mark: | :heavy_check_mark:  | :x:                 |
| Delete Attribute   | :heavy_check_mark: | :heavy_check_mark:  | :x:                 |
| Create Value       | :heavy_check_mark: | :heavy_check_mark:  | :x:                 |
| Read Value         | :heavy_check_mark: | :heavy_check_mark:  | :heavy_check_mark:  |
| Update Value       | :heavy_check_mark: | :heavy_check_mark:  | :x:                 |
| Delete Value       | :heavy_check_mark: | :heavy_check_mark:  | :x:                 |

## Syntax: SQLAlchemy as JSON

在上方的舉例中我們已經看見 SQLAlchemy 可以滿足 Advanced Filter 這個新功能，且先前 Internal API 的實作也全然仰賴 SQLAlchemy，因此只要 ODQL 能夠完美映射成 SQLAlchemy Query，我們將既能滿足新需求，也能相容 Internal API 所能提供的任意查詢。

由於時程壓力，開發團隊沒有充足的時間重新發明 ODQL 的語法，因此優先採用目前發展非常成熟的 JSON 格式作為 Query 語法，這將能替我們節省開發 Syntax Parser 的時間。

至此，如何實作 ODQL 的問題已經被簡化成另一個等價的命題了：

> 如何將 SQLAlchemy 的 ORM Query 表達成 JSON 格式？

## Expression Tree

在多數程式語言裡，我們通常能將 expression 表示成一顆樹狀的結構，稱為 Expression Tree。而 Tree 的一大好處在於我們可以很容易使用 JSON 的形式來表現，因此我們的原命題可以再次修正為：

> 如何將 SQLAlchemy 的 ORM Query 表達成 Expression Tree？

## Operators, Entities and Columns

如果你對 SQLAlchemy Query 足夠熟悉，應該可以知道它的運算元包含了 `==`, `!=`, `>`, `<`, `>=`, `<=`, `and_()`, `or_()`, `not_()`, `q.intersect()`, `q.union()`, `q.offset()`, `q.limit()`, ...，按照運算子的類型分類後便能更加一目瞭然：

- Entity Level
    - `q.$$intersect(qs:[Query])`
    - `q.$$union(qs:[Query])`
    - `q.$$limit(limit:int, q:Query)`
    - `q.$$offset(offset:int, q:Query)`
    - `q.$$order_by(field_path:str, order:'asc'|'desc', null_order:'nullsfirst'|'nullslast', q:Query)`
- Column Level
    - `c<T>.$eq(value:T)`
    - `c<T>.$ne(value:T)`
    - `c<T>.$gt(value:T)`
    - `c<T>.$lt(value:T)`
    - `c<T>.$ge(value:T)`
    - `c<T>.$le(value:T)`
    - `c<T>.$in(values: [T])`
    - `c<str>.$like(case_sensitive:bool, pattern:str)`
- Binary Expression
    - `$and(bin_exps:[BinaryExpression])`
    - `$or(bin_exps:[BinaryExpression])`
    - `$not(bin_exps:[BinaryExpression])`

因此我們便能夠定義出 ODQL 的 Operator Set 以及 Operands 彼此間的 Expression Tree 範式了：

```
entity_level_query =
  { <entity_name>: column_level_query } |
  { <entity_level_operator>: *(operands ∪ entity_level_queries) }
column_level_query =
  {
    <column_name>:
      { <column_level_operator>: *operands } |
      column_level_query
  } |
  { <binary_operator>: *column_level_queries }
```

例如：

```json
{
  "offset()": [
    666,
    {
      "intersect()": [
        {
          "policies": {
            "and_()": [
              {
                "is_latest": {
                  "==": true
                }
              },
              {
                "effective_time": {
                    ">=": "2021-11-05 00:00:00+00:00"
                }
              }
            ]
          }
        },
        {
          "policies": {
            "not_()": [
              {
                "product": {
                  "state": {
                    "==": "launched"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}
```

## Query Specific Columns

目前為止，雖然我們已經滿足了查詢條件的語法，但是使用者還沒辦法指定最終要取得的欄位，因此必須再次變更範式的設計，納入欄位選取的考量：

```
entity_level_query =
  {
    <entity_name>: {
      "fields": fields_expression
      "filter": column_level_query
    }
  } |
  { <entity_level_operator>: *(operands ∪ entity_level_queries) }

field_name = "field_name[,field_name]"
fields_expression = "{field_name[fields_expression]}"
```

例如：

```json
{
  "policies": {
    "fields": "{id,name,insured_subjects{id},product{state},create_time}",
    "filter": ...
  }
}
```

## Query Multiple Entities

在 RESTful 的時代，如果要取得多個 Entities 下的內容，通常要連打幾支不同的 API，不僅拉長了 TTI（Time to Interactive），如果應用程式對資料一致性有特殊要求，甚至可能因為 DB 併發導致看到不一致的 Response Data。在參考 GraphQL 的設計之後，ODQL 也納入了 Multiple Entities 的查詢，讓我們再次修改範式：

```
cross_entity_query = {
  "queries": *entity_level_queries
}
```

## Endpoint

考慮與 FE 整合的難易度，連線上仍然採用 HTTP。但是考慮到先前 Internal API 曾經遇過 URL 長度超過 Gunicorn 的預設限制（`--limit-request-line 4094`），且 ODQL 雖然現階段只有 Read Only，但未來不排除實作 Update & Delete Entities，因此 HTTP Verb 最終選擇了 POST，fields 及 query 則帶在 Request Body：

```
POST /odql <cross_entity_query>
```

## Implementation

完整實作涉及公司機密，就憑各位讀者的造化了。

## Pros & Cons

ODQL 並非萬靈丹，我們開發它只是為了滿足大部分日常需求，雖然它的確補足了 Internal API 的一些不便，卻也產生了需要取捨的成本，以下總結了幾項利弊，讓大家更曉得使用新工具的同時有哪些仍需注意的事項。

**優點**：

- 提供良好的查詢完備性
- Request 長度較不受限
- 可以一次查詢多個 Entities，且達到 Atomic 的特性
- 可自訂 Fields 語法（例如：未來可新增語法來支援 Attribute 查詢、未來可新增聚合結果的查詢）

**缺點：**

- 由於使用 POST，所以可能需要特別處理 Request Body 的 Logging
- 查詢結果永遠是一包集合，無法像 RESTful 般查詢單一且特定的 Instance
- 無現成工具提供 FE 進行整合

## Integration with React

目前在 OneDegree 內部以使用 React 為主，因此與 FE 的整合上建議以 React Hook 的介面來串接最為乾淨俐落，且 ODQL 仍為實驗性質的嘗試，不宜與專案建立過多耦合，保持 Functional 的寫法仍是上策。

初期使用上建議以撰寫 Raw Query 為主：

```jsx
const MyComponent = () => {
  const { countries, timezones } = useODQL({
    'countries': {
      'fields': '{id}',
      'filter': {...}
    },
    'timezones': {
      'fields': '{id}',
      'filter': {...}
    }
  })

  return (
    ...
  )
}
```

使用上較為穩定成熟後可以考慮簡易封裝，例如 Builder Pattern：

```jsx
const MyComponent = () => {
  const { QueryBuilder } = useODQL()
  policies = QueryBuilder()
    .intersect_with_queries([
      QueryBuilder()
        .set_entity('policies')
        .set_fields('{id,number,insured_subjects{id,name}}')
            .set_filter({
              'is_latest': {
                '$eq': true
              }
            })
        .build(),
      QueryBuilder()
        .set_entity('policies')
        .set_fields('{id,number,insured_subjects{id,name}}')
            .set_filter({
              'create_time': {
                '$gt': '2021-11-07 00:00:00+00:00'
              }
            })
        .build()
    ])
    .set_offset(0)
    .set_limit(10)
    .build()
    .fetch()

　return (
    ...
  )
}
```

# 參考資料

- MongoDB Query Language (MQL)
- GraphQL


如何替你的產品設計一套查詢語言？以ODQL: OneDegree Query Language為例


在某次行銷活動前，後端團隊雖然知道即將會有比平常更多的流量，但苦於先前沒有舉辦過類似的行銷活動，也就沒有系統的歷史監控數據可以參考，因此無法提供 SRE 一個合理的數字讓他們加開虛擬機，這將使我們的服務在行銷檔期內可能無法維持高可用，甚至無法確保 SLO 的水準。

那麼我們有沒有其他方法可以計算需要加開的虛擬機數量呢？

既然沒有相似的行銷活動數據，此時我們能仰賴的就只有系統日常的已知事實，如果再搭配數學模型預測檔期間的流量，便能簡易預測要做多少準備工作了。

**已知事實**

從 SRE 的監控系統中可以獲得下列資訊：

- 平均每小時累計 3,000 個請求
- 每台 VM 平均負擔 2 QPS

**數學模型**

由於我們不曉得自己的服務的 QPS 分佈是否屬於某種已知分佈，只好先粗暴地假設在每個小時內的 QPS 服從`常態分佈`。

**預測目標**

最終目標是維持服務的高可用性，即每一個服務請求都要能被虛擬機處理且沒有遺漏。這意味著我們的叢集內必須常駐著特定數量的虛擬機，才足以處理尖峰時段的流量。（舉例來說，每台虛擬機負擔 2 QPS，尖峰時段達到 11 QPS，則可以預期需要 6 台虛擬機才足以維持服務高可用）所以我們要計算的對象其實是尖峰時段的 QPS，也就是 QPS 的最大值。

## 命題

綜上所述，我們可以重新整理一下此情境真正要解決的問題：

> 已知服務平均每小時累計 3,000 個請求，每台 VM 平均負擔 2 QPS，請假設 QPS 服從常態分佈，求 QPS 最大值為多少？VM 至多需要幾台？

## 推導

根據常態分佈的特性，我們已知隨機變數 $x$ 的機率密度函數為：

$$$
p = f(x) = \frac{1}{\sigma\sqrt{2\pi}}e^{-\frac{(x-\mu)^2}{2\sigma^2}}
$$$

且函數 $f(x)$ 曲線下面積為 $1$：

$$$
\int_{-\infin}^{\infin}f(x)dx = 100\% = 1
$$$

且 $x$ 在平均數 $\mu$ 的三倍標準差($\sigma$)以內的 $f(x)$ 曲線下面積約佔全面積的 99.7%：

$$$
\int_{\mu-3\sigma}^{\mu+3\sigma}f(x)dx = 99.7\%\times\int_{-\infin}^{\infin}f(x)dx = 99.7\%\times 1 = 0.997
$$$

如果將此情況類推到我們的情境中，則隨機變數相當於時間 $t$，假設 $t$ 的單位為秒，則機率密度相當於 QPS，$q$：

$$$
q = g(t) = \frac{1}{\sigma\sqrt{2\pi}}e^{-\frac{(t-\mu)^2}{2\sigma^2}}
$$$

函數 $g(t)$ 曲線下面積相當於總請求數量，可知 $g(t)$ 在一小時 3600 秒的範圍內累積了 3000 個請求：

$$$
\int_{\mu-3\sigma}^{\mu+3\sigma}g(t)dt = 3000
$$$

假設這 3600 秒恰好涵蓋 99.7% 的請求總數，則從邊界的計算可推得標準差 $\sigma = 600$：

$$$
(\mu+3\sigma) - (\mu-3\sigma) = 3600\Rightarrow
\sigma = 600
$$$

再從面積的計算可推導 $g(t)$ 曲線下面積約為 $f(x)$ 曲線下面積的 3009 倍：

$$$
\int_{-\infin}^{\infin}g(t)dt = \frac{3000}{0.997} = 3009 = 3009\times\int_{-\infin}^{\infin}f(x)dx
$$$

即 $g(t)$ 與 $f(x)$ 為線性關係：

$$$
g(t) = 3009 \times f(x)
$$$

而所求 QPS 最大值即為 $g(x)$ 最大值，發生在當 $t = \mu$ 或 $x = \mu$ 時：

$$$
g(\mu) = 3009 \times f(\mu) = 3009 \times \frac{1}{\sigma\sqrt{2\pi}} = \frac{3009}{600\sqrt{2\times3.14}} = 2
$$$

可知 VM 至多需要 $2 / 2 = 1$ 台


QPS 預測


謹以此文紀錄軟體開發時偶爾派上用場的數學。

那些我在軟體開發中使用到的數學


入職數位行銷產業近半年，當初的我沒有任何數位廣告的Knowhow，硬著頭皮就開始寫code了，每次開會或討論時，總有新的名詞會打斷我的思緒，當初的我多麼希望有一份文件可以補足工程師進入廣告產業時應該認識的知識，降低新人上手的門檻。然而時至今日，我還是沒能看到心目中期盼著的那份文件，但此時的我已稍有數位廣告供應商的經驗，因此決定自己執筆，希望提供後人一條捷徑，避免更多後輩一邊工作一邊抱著「要是當初有這篇文章該有多好」的遺憾。另外，畢竟小弟是個外行人，如文中有誤，也敬請見諒。

# 專詞介紹

數位廣告是一個龐大的體系，可以把它想像成一個巨大的供需市場，裡面有企業主想透過廣告進行行銷，也有網站主或媒體想透過提供廣告版位來獲利。這裡條列出幾個經常出現在會議及討論裡的行話，並且搭配我自己的認知來詮釋，也歡迎自行Google更詳細更嚴謹的解釋。

## 常見角色劃分

- 受眾（Audience）：實際被廣告推銷的一方
- 網站主（Publisher）：掌握流量並且想藉由販售廣告版位營利的一方
- 廣告主（Advertiser）：有預算想進行行銷的一方
- SSP（Supply Side Platform）：提供廣告供應方（網站主）出售版位的服務平台
- DSP（Demand Side Platform）：提供廣告需求方（廣告主）刊登廣告的服務平台
- DMP（Data Management Platform）：管理受眾資訊及提供精準投放服務的平台
- Ad Server：真正存放及供應廣告素材的伺服器
- 廣告聯播網（Ad Network）：搓合廣告交易的中間供應商，可能同時提供了SSP、DSP及各種廣告生態中的服務

## 常見術語

- 版位（Inventory）：可放置廣告的容器，經常是固定大小且處於固定的排版位置，在各種廣告交易之中，實際上被販售的就是inventory，此用語較常使用於商務上的描述
- 廣告單元（Ad Unit/Ad Tag）：實際埋入廣告版位裡的可執行程式碼片段，如HTML標籤或javascript，此用語較常使用於工程或開發上的描述
- 廣告素材（Creative）：實際可視的投放內容，例如圖片、影片、Flash動畫等
- Targeting：精準行銷，將廣告精確地投放到適當的受眾
- Passback：主要的曝光方式無法完成曝光時的次要曝光方式。例如Publisher P設定Advertiser A1的廣告優先於Advertiser A2，當A1不願出價購買目前流量時，稱passback給A2，再由A2繼續決定是否購買流量

## 其他

- DFP（Doubleclick for Publishers）：Google的SSP服務
- 委刊項（Line Item）：用於Targeting受眾的設定，可以設定成鎖定特定性別、年齡層、...，也可以設定為自訂值

# 數位廣告是如何運作的？

認識完名詞，接下來該來談談廣告運作的流程了，以下我們用比較工程的角度來切入，看看數位廣告的pipeline究竟長什麼樣子

1. Publisher在自己的產品裡（無論是Web或是App）埋入`Ad Tag`
2. End User載入網頁時，Ad Tag執行Javascript向DMP查詢目前Traffic應該Targeting給何種受眾
  可以想像Response會是如同下面所示的Json：
  ```
  {
    "targeting": {
      "gender": "male",
      "age": [15, 25],
      "country": "TW"
    }
  }
  ```
3. Ad Tag將不同DMP的Targeting結果合併後轉送至Ad server取得合適的Creative
4. Creative經瀏覽器渲染後`Serve`廣告內容
  可能是Banner/Display、Interstitial、Vast、Multi-Media、Native等各種性質的廣告
5. Creative發送Show/Click/Action等追蹤廣告成效用的Beacon給各自的Ad Network
6. SSP根據收集到的Beacon統計成廣告成效報表，出帳給Publisher
7. Ad Network內的服務根據不斷累積的流量，持續修正交易策略（如：出價模式、投放行為）

# 廣告概觀

除了上述較為工程導向的介紹，本章節從營運的角度來看，了解更多背景知識及詞彙，幫助我們更加理解整個領域的生態。

## 廣告類型：傳統廣告（Traditional Advertising）vs. 數位廣告（Digital Advertising）

相信大家對廣告早就不感到陌生了，從電視、電台、報章雜誌、平面廣告、車體、戶外電視牆/看板，到捷運燈箱等通路（Channel），總是能看到五花八門的廣告，這種`固定檔期、固定投放量、固定售價`的廣告就屬於傳統廣告。

反之，隨著電腦科技演進而發展出來，可以透過程式自動進行的廣告交易就屬於數位廣告，相較於傳統廣告，對廣告主（Advertiser）而言更容易追蹤成效，對網站主（Publisher）而言也能提升營收。

## 廣告交易方式：直售廣告（Direct-Sold）vs. 程式化廣告（Programmatic Advertising）

從歷史演進的角度來看，傳統廣告屬於直售廣告（Direct-Sold），通常有人為介入、買賣廣告版位、必須事先預定、計價模式採用固定價錢（CPM）；隨著電腦科技發展，廣告的交易逐漸數位化，因而發展出程式化廣告（Programmatic Advertising），由電腦程式代操廣告交易，特色為非人為、買賣廣告受眾、即時競價、計價模式採用動態出價（eCPM），程式化廣告除了能將傳統的直售廣告程式化以外，甚至演化出程式化廣告才能辦到的即時競價廣告（Real Time Bidding，RTB）。

## 競價策略：瀑布流（Waterfall）vs. 即時競價（Real Time Bidding，RTB）

常見的程式化廣告競價策略包括Waterfall及Real Time Bidding，通常Publisher會兩者並用來使營收最大化。在Waterfall策略中，Publisher能夠給予各家DSP不同的優先次序（Priority）；相對地，在RTB策略中，各家DSP都必須被設定成同樣的Priority，藉此使不同的DSP在公平的環境下競價。

### Waterfall

Waterfall指的是各家DSP被Publisher設定成不同的優先次序，每一輪拍賣中，廣告版位由次序最高者流向次序最小者，依序詢問DSP是否願意出價，一旦目前被詢問到的DSP願意出價，且出價高於Publisher設定的底價（Floor Price），則該DSP標得版位（Fill），否則版位繼續流向下一家DSP詢問出價（Passback）。

下圖是一種Waterfall的範例：直售受到人為影響，可能簽署了合約，Priority因此最高，接著依序進入程式化廣告、PMP（Private Market Place，不在本文討論範疇）、ADX、AdSense，如果以上Demand Partners都未參與競價，則版位最終流入House。

![](./waterfall.png "Waterfall範例（圖片來源：https://www.sales-frontier.com/publisher.php）")

實作Waterfall的方式有許多種，例如在DFP上可以透過設定`Line Item Type`改變Priority；或者，我們也可以透過SSP上的介面來設定各家DSP的Creative來達到Waterfall的效果（如將A公司的Passback Creative設定為B公司的Creative，使A公司有較高的Priority）。

### RTB

參與同一個inventory拍賣的各家DSP會幾乎在同一時間收到impression，並決定是否出價，版位由出價最高者標得，但只需支付次高的標價（此機制稱為Second-price Auction，有利於DSP掌握市場行情），整個拍賣過程必須在一定時間內完成（通常是數百毫秒），逾時的DSP將直接被淘汰。

IAB（Interactive Advertising Bureau，互動廣告協會）制定了許多廣告界的標準，其中`OpenRTB`就是因應RTB所設計的標準，例如制定各家DSP必須在`200ms`以內完成拍賣競價。

# RTB現況

## Header Bidding

Header Bidding可以說是RTB在網頁技術中的一種表現形式，網頁可以很粗略地分為`<head>`及`<body>`，Publisher會在`<head>`中埋入SSP提供的競價所需的程式碼，當瀏覽器解析完這段程式碼時就會觸發即時競價，因此Bidder在網頁內容不可知的情況下獲得first look的traffic，僅能由cookie或封包header資訊判斷是否要出價。

## Bidder

所謂的競價，其實就是Publisher埋入的程式碼會向Bidder發出POST請求，並且夾帶cookie、版位的id、該輪拍賣的uuid等相關資訊。而Bidder是一個伺服器端的程式，透過暴露出來的Endpoint接收客戶端的競價請求，背後則是依照各家服務自行實作，可能會串接AI模型來推論traffic的價值，也可能需要連接Ad Server，當需要出價時，連同Creative一起送回客戶端。

## Prebid

Prebid是由AppNexus開源的Header Bidding實作，可用於網頁及行動裝置。它的運作原理其實是濫用DFP的Line Item，Publisher必須在DFP建立許多Line Items，並且分別設置不同Key-Value來Target不同的價格區間（Price Bucket），然而這些Line Item都必須綁定到相同的Creative Set，如此一來，End User打開安裝了Prebid的網頁時將會依序發生下面的事件來曝光廣告：

1. 載入Prebid JS Library
2. Prebid初始化Publisher的設定，例如版位A要使用B1及B2兩個Bidder、版位B要使用B1,B2,B3三個Bidder
3. Prebid根據Publisher的設定，發送競價請求給各家Bidder
4. 各家Bidder回應出價及Creative
5. Prebid篩選出各版位的得主，並向DFP發送Targeting請求，且Key設定為得主，Value設定為得標價的最近價格區間
6. DFP回應Creative
7. Prebid渲染Creative

# Ad Operation

Campaign：一次有始有終的行銷活動，如：雙11檔期
Order
Inventory

# 廣告成效（Performance）

## Funnel

Traffic/Request -> Bid -> Bid Won -> Viewability -> Show/Impression -> Click -> Action(註冊、安裝App、加入購物車、付款、...)

## 常用指標

- Fill Rate
- CTR（Click-Through Rate）：點擊率
- CVR（Conversion Rate）：廣告轉換率
- ROI（Return on Investment）：投資報酬率

## 計價模式

對Advertiser：每千次曝光/點擊/行為所花費的廣告預算
- CPM（Cost Per Mille）
- CPC（Cost Per Click）
- CPA（Cot Per Action）

對Publisher：每千次曝光所獲得的廣告營收
- eRPM（effective cost per mille）

# 衍生議題

## Discrepancy

## Fraud

可以透過redis deduplicate來消除短時間內（如：一小時）的重覆impression

## Advertising on AMP-enabled Page

## 髒髒的SSP

之前遇過某家SSP在auction結束後偷偷蒐集各家bidder的出價，雖然技術上可行，也算不上犯了什麼濤天大罪，但被抓到肯定永遠被貼上「商業手法不乾淨」的標籤，於是隔天這家髒髒的SSP就被Publisher拔掉了

## 千萬不要在公司瀏覽器裝Adblock

真的是切身之痛

## Safari直接禁止third-party cookie？

# 參考資料

- [Online Advertising and Ad Tech Glossary](https://wiki.xandr.com/display/industry/Online+Advertising+and+Ad+Tech+Glossary)
- [Key Differences between Direct-Sold and Programmatic Advertising](https://blog.ad-juster.com/differences-between-direct-sold-and-programmatic-advertising/)
- [Stop Confusing Programmatic with Real-time Bidding](https://smartyads.com/blog/stop-confusing-programmatic-with-real-time-bidding/)
- [Real-time bidding](https://en.wikipedia.org/wiki/Real-time_bidding)
- [RTB市场下使用second price的意义何在？](https://www.zhihu.com/question/28189350)


工程師進入數位廣告產業的正確姿勢

廣告類型：傳統廣告（Traditional Advertising）vs. 數位廣告（Digital Advertising）

廣告交易方式：直售廣告（Direct-Sold）vs. 程式化廣告（Programmatic Advertising）

競價策略：瀑布流（Waterfall）vs. 即時競價（Real Time Bidding，RTB）