FastAPI 最佳实践

作者：Holts 时间：2023年07月15日分类：编程字数：4541

FastAPI 最佳实践

虽然FastAPI是一个有着出色文档的伟大框架，但对于初学者来说，如何构建大型项目并不是那么明显。

在过去的1.5年中，我们做出了好的和坏的决定，这些决定对我们的开发人员体验产生了巨大的影响。其中一些值得分享。

项目结构。一致且可预测
过度使用Pydantic进行数据验证
使用依赖项进行数据验证而不是DB
解耦和重用依赖项。依赖调用被缓存
如果只有阻塞I/O操作，请勿使你的路由异步
迁移。Alembic
BackgroundTasks > asyncio.create_task
小心动态的Pydantic字段
分块保存文件
如果必须使用同步SDK，请在线程池中运行。 本文仅包含我们遵循的准则的一部分，所以请随意找到带有详细最佳实践完整列表的 原始GitHub存储库，它已经获得了一些积极的反馈（在 r/Python 中成为了一天的热门帖子，并在第一周内获得了250个星标）.

项目结构。一致且可预测

有许多方法可以构建项目，但最好的结构是一种一致、简单明了且没有惊喜的结构。

如果查看项目结构不能让你了解项目的内容，则结构可能不清晰。
如果你必须打开包才能了解其中包含的模块，则你的结构不清晰。
如果文件的频率和位置感觉随机，则你的项目结构很糟糕。
如果查看模块的位置和名称不能让你了解其中的内容，则你的结构非常糟糕。

虽然我们使用的项目结构是由 Sebastián Ramírez 提出的，该结构将文件按其类型（例如API、CRUD、模型、模式）分开，适用于微服务或具有较少范围的项目，但是我们无法将其适用于具有许多域和模块的单块。

我发现更具可扩展性和可演变性的结构是受Netflix的 Dispatch启发，有一些小修改。

fastapi-project
├── alembic/
├── src
│ ├── auth
│ │ ├── router.py
│ │ ├── schemas.py # pydantic models
│ │ ├── models.py # db models
│ │ ├── dependencies.py
│ │ ├── config.py # local configs
│ │ ├── constants.py
│ │ ├── exceptions.py
│ │ ├── service.py
│ │ └── utils.py
│ ├── aws
│ │ ├── client.py # client model for external service communication
│ │ ├── schemas.py
│ │ ├── config.py
│ │ ├── constants.py
│ │ ├── exceptions.py
│ │ └── utils.py
│ └── posts
│ │ ├── router.py
│ │ ├── schemas.py
│ │ ├── models.py
│ │ ├── dependencies.py
│ │ ├── constants.py
│ │ ├── exceptions.py
│ │ ├── service.py
│ │ └── utils.py
│ ├── config.py # global configs
│ ├── models.py # global models
│ ├── exceptions.py # global exceptions
│ ├── pagination.py # global module e.g. pagination
│ ├── database.py # db connection related stuff
│ └── main.py
├── tests/
│ ├── auth
│ ├── aws
│ └── posts
├── templates/
│ └── index.html
├── requirements
│ ├── base.txt
│ ├── dev.txt
│ └── prod.txt
├── .env
├── .gitignore
├── logging.ini
└── alembic.ini

当一个包需要其他包的服务或依赖项时，请使用显式模块名称导入它们。

from src.auth import constants as auth_constants
from src.notifications import service as notification_service
from src.posts.constants import ErrorCode as PostsErrorCode

过度使用Pydantic进行数据验证

Pydantic具有丰富的功能，可验证和转换数据。

除了常规功能，如具有默认值的必需和非必需字段之外，Pydantic还具有内置的全面数据处理工具，如正则表达式、限制允许选项的枚举、长度验证、电子邮件验证等。

使用依赖项进行数据验证而不是DB

Pydantic只能验证客户端输入的值。使用依赖项验证数据是否符合数据库约束，例如电子邮件已存在、未找到用户等。

作为奖励，使用常见依赖项可以消除为每个这些路由编写测试以验证post_id的需要。

解耦和重用依赖项。依赖调用被缓存

依赖项可以多次重复使用，它们不会被重新计算——FastAPI默认情况下在请求范围内缓存依赖项的结果，即如果我们有一个调用服务 get_post_by_id 的依赖项，则每次调用此依赖项时我们不会访问DB-仅在第一次函数调用时。

了解这一点，我们可以轻松地将依赖项解耦为多个较小的函数，这些函数在较小的域上运行，更容易在其他路由中重用。例如，在下面的代码中，我们使用 parse_jwt_data 依赖项三次：

valid_owned_post
valid_active_creator
get_user_post， 但 parse_jwt_data 仅在第一个调用中调用。

如果只有阻塞I/O操作，请勿使你的路由异步

在幕后，FastAPI可以有效地处理异步和同步I/O操作。

FastAPI在线程池中运行 sync 路由，阻塞I/O操作不会阻止事件循环执行任务。
否则，如果路由定义为 async，则会通过 await 正常调用，FastAPI相信你只会执行非阻塞I/O操作。

注意事项是，如果你不信任并在异步路由中执行阻塞操作，则事件循环将无法运行下一个任务，直到该阻塞操作完成。

第二个注意事项是，非阻塞可等待操作或发送到线程池的操作必须是I/O密集型任务（例如，打开文件、DB调用、外部API调用）。

等待CPU密集型任务（例如，重型计算、数据处理、视频转码）是无用的，因为CPU必须工作才能完成任务，而I/O操作是外部的，服务器在等待这些操作完成时什么都不做，因此可以转到下一个任务。
在其他线程中运行CPU密集型任务也不起作用，因为GIL。简而言之，GIL一次只允许一个线程工作，这使得它对CPU任务无用。
如果要优化CPU密集型任务，应将它们发送到另一个进程中的工作程序。

迁移 Alembic。
迁移必须是静态且可还原的。如果你的迁移依赖于动态生成的数据，请确保唯一动态的是数据本身，而不是其结构。
使用具有描述性名称和短标识的迁移。标识是必需的，应解释更改。
为新迁移设置可读的文件模板。我们使用 date_slug.py 模式，例如 2022-08-24_post_content_idx.py

alembic.ini

file_template = %%(year)d-%%(month).2d-%%(day).2d_%%(slug)s

BackgroundTasks > asyncio.create_task

BackgroundTasks 可以有效地运行阻塞和非阻塞 I/O 操作，就像处理路由一样（同步函数在线程池中运行，而异步函数稍后会被等待执行）。

不要欺骗工作线程，也不要将阻塞 I/O 操作标记为“async”。
不要将其用于重量级 CPU 密集型任务。

分块保存文件

不要指望客户端只发送小文件。

动态 pydantic 字段需谨慎处理

如果你有一个 pydantic 字段可以接受类型的联合，请确保验证器明确知道这些类型之间的区别。

非常糟糕的解决方案：

适当地对字段类型进行排序：从最严格的到最宽松的。

验证输入是否只包含有效字段。

Pydantic 会忽略联合类型的 ValueError 并迭代它们。如果没有类型是有效的，则会引发最后一个异常。

如果字段简单，则使用 Pydantic 的智能联合（>v1.9）

如果字段很简单，比如 int 或 bool，这是一个很好的解决方案，但它对于像类这样的复杂字段无效。

没有智能联合的情况：

使用智能联合的情况：

如果必须使用同步 SDK，则在线程池中运行

如果必须使用 SDK 与外部服务进行交互，并且它不是“async”，则在外部工作线程中进行 HTTP 调用。

举个简单的例子，我们可以使用我们熟知的 starlette 的 run_in_threadpool。

FastAPI 是一个工具，可以轻松构建简单和复杂的项目。不是缺少上述规则而导致了难以维护的项目，而是缺乏一致性。

无论你有什么规则，唯一应该遵循的规则就是遵循你的规则的一致性。找到一组有效的约定，对其进行迭代，并将其向他人宣传。如果你已经有了这样的约定，请在问题页面上与其他人分享。

译自：https://betterprogramming.pub/fastapi-best-practices-1f0deeba4fce

FastAPI 开发模板

作者：Holts 时间：2023年07月15日分类：编程字数：2789

FastAPI Example Project

Some people were searching my GitHub profile for project examples after reading the article on FastAPI best practices.
Unfortunately, I didn't have useful public repositories, but only my old proof-of-concept projects.

Hence, I have decided to fix that and show how I start projects nowadays, after getting some real-world experience.
This repo is kind of a template I use when starting up new FastAPI projects:

production-ready
- gunicorn with dynamic workers configuration (stolen from @tiangolo)
- Dockerfile optimized for small size and fast builds with a non-root user
- JSON logs
- sentry for deployed envs
easy local development
- environment with configured postgres and redis
- script to lint code with black, autoflake, isort (also stolen from @tiangolo)
- configured pytest with async-asgi-testclient, pytest-env, pytest-asyncio
- fully typed to comply with mypy
SQLAlchemy with slightly configured alembic
- async db calls with asyncpg
- set up sqlalchemy2-stubs
- migrations set in easy to sort format (YYYY-MM-DD_slug)
pre-installed JWT authorization
- short-lived access token
- long-lived refresh token which is stored in http-only cookies
- salted password storage with bcrypt
global pydantic model with
- orjson
- explicit timezone setting during JSON export
and some other extras like global exceptions, sqlalchemy keys naming convention, shortcut scripts for alembic, etc.

Local Development

First Build Only

cp .env.example .env
docker network create app_main
docker-compose up -d --build

Linters

Format the code

docker compose exec app format

Migrations

Create an automatic migration from changes in src/database.py
```
docker compose exec app makemigrations *migration_name*
```
Run migrations
```
docker compose exec app migrate
```
Downgrade migrations
```
docker compose exec app downgrade -1  # or -2 or base or hash of the migration
```
Tests
All tests are integrational and require DB connection.

One of the choices I've made is to use default database (postgres), separated from app's app database.

Using default database makes it easier to run tests in CI/CD environments, since there is no need to setup additional databases
Tests are run with force_rollback=True, i.e. every transaction made is then reverted

Run tests

docker compose exec app pytest

Documentation

swagger - http://localhost:8000/docs
redoc - http://localhost:8000/redoc

Waxy 简约自适应博客主题

作者：Holts 时间：2023年07月09日分类：默认分类字数：5044

Waxy 简约自适应博客主题

在线预览(稳定) | 在线预览(测试) | 更新计划 | 问题反馈

Waxy，白蜡。白为色之祖，简而百搭；蜡，轻而易雕琢；

Waxy（白蜡），代表着本主题的特点------轻量高效，悦于书写！

小巧，却拥有完善且丰富的功能。

即可开箱即用，也可以加以雕琢。简约的设计，无限的可能！

呐，朋友。

尺牍已展，静候佳作！

Waxy 简约自适应博客主题

本主题参考seventeen主题，由其修改更新而来，感谢原作者的辛苦付出！

安装主题

主题下载地址：GitHub & CDN

MD5: C514E80FE10F5F9DAE286A98E58EB61A

SHA1: D7B316AAACE090D4CD8B4AB7837DC0D7366C5421

把主题上传到 Typecho 安装路径下的 usr/themes/ 目录，然后解压，你也可以先解压在上传。

解压完成后，请将主题目录重命名为Waxy，并保证所有主题文件在此目录下。

如需修改主题设置，请点击设置外观进入主题设置。

主题功能介绍

轻量高效，悦于书写
响应式布局
图片懒加载/灯箱
自定义侧边栏/JS/CSS样式
文章置顶/标星/首图/内容失效提醒/阅读剩余部分
短代码快捷功能（多彩提示框/多彩文字提示/简易提示框/收缩框/快捷插入音频&视频）
置顶公告/CDN切换/代码高亮/时间线/归档页面/Sitemap/技术统计

短代码

短代码可以快速为你提供更多展示效果。使文章层次更丰富。

效果

短代码效果

使用方法

#多彩提示框
info:一般提示
warning:警告提示
Error:危险提示
info:多行内容测试：<br />
生活如酒，或芳香，或浓烈，因为诚实，它变得醇厚；生活如歌，或高昂，或低沉，因为守信，它变得悦耳； 生活如画，或明丽，或素雅，因为诚信，它变得美丽。


#文字提示
警告文字样式
高亮文字样式
备注文字样式


#插入视频（支持视频静音，自动播放，循环播放）


#插入音频（支持自动播放，循环播放）


#PS：某些浏览器限制，可能无法自动播放，不过一般静音视频不受影响~


#简易提示框（添加close="close"，可以激活关闭按钮）
简易提示框：success，默认样式
简易提示框：info
简易提示框：warning
简易提示框：danger


#收缩框（添加checked="checked"，自动展开收缩框；style，控制外观样式）

                        "收缩框：默认样式，自动展开"
内容

                        "收缩框：primary"
内容

                        "收缩框：success"
内容

                        "收缩框：info"
内容

                        "收缩框：warning"
内容

                        "收缩框：danger"
内容

代码高亮

基于prism.js实现，自带8种主题。

代码高亮设置

移植于CodeHighlighter-for-Typecho插件，感谢原作者的辛苦劳动！

自定义侧边栏

自定义CSS/JS

PS:通过与置顶公告联动，还可以实现一言效果~

hitokoto

友情链接管理

一行一条，格式(请用半角空格或逗号分隔)：网站名称,网站地址,网站图标(建议:32x32),网站说明

友情链接管理

文章首图

如果想使用首图，请在文章自定义字段 img 添加网址即可

文章标星

如果想在文章右上角显示一个显眼的标记，请添加文章自定义字段 star 即可

star

文章内容失效提醒

remind

置顶公告&文章

top

2020/10/05可以同时置顶多篇文章，滚动展示。

多篇文章置顶效果：

top

阅读剩余部分

在需要截断文章的位置插入即可

#时间线使用方法

#新建独立页面，选择模板为 时间线 即可。并在其中按如下格式填写即可

- **<红色的标题内容>** <气泡的内容，支持图片，超链接，短代码>
- **<红色的标题内容>** <气泡的内容，支持图片，超链接，短代码>
- **<红色的标题内容>** <气泡的内容，支持图片，超链接，短代码>
- **<红色的标题内容>** <气泡的内容，支持图片，超链接，短代码>

其中 - 是markdown语法中的无序列表，** **是markdown语法中的文字加粗。< >是您自定义的内容，使用时请去掉尖括号。

page_articles

归档页面

#归档页面，由系统自动生成。

您只需要新建独立页面，选择模板为 归档页面 即可。

page_timeline

友情链接页面

#使用方法

#新建独立页面，选择模板为 友情链接 即可。并在其中按如下格式填写即可，空行间隔可分片

- [![<网站地址>](<网站图片> )](<网站URL>)

page_friends.png

Sitemap/网站地图

百度/谷歌站长工具正常收录

百度/谷歌站长工具正常收录

Bing站长工具正常收录

标准模式和纯文本模式（添加参数?txt=1）

标准模式和纯文本模式（添加参数?txt=1）

启用Sitemap/网站地图

Markdown 简明语法手册

作者：Holts 时间：2023年07月02日分类：默认分类字数：7365

Markdown 简明语法手册

========================================================================

标签： Markdown

我们需要更便捷更高效的工具记录思想，整理笔记、知识，并将其中承载的价值传播给他人，Markdown 是我们给出的答案 —— 我们为记录思想和分享知识提供更专业的工具。

整理知识，学习笔记
发布日记，杂文，所见所想
撰写发布技术文稿（代码支持）
撰写发布学术论文（LaTeX 公式支持）

什么是 Markdown

Markdown 是一种方便记忆、书写的纯文本标记语言，用户可以使用这些标记符号以最小的输入代价生成极富表现力的文档：譬如您正在阅读的这份文档。它使用简单的符号标记不同的标题，分割不同的段落，粗体或者斜体某些文字，更棒的是，它还可以

制作一份待办事宜Todo列表
书写一个质能守恒公式
高亮一段代码
高效绘制流程图
高效绘制序列图
高效绘制甘特图
绘制表格

Markdown 语法

1. 斜体和粗体

使用和 * 表示斜体和粗体。

示例：

这是斜体，这是粗体。

2. 分级标题

使用 === 表示一级标题，使用 --- 表示二级标题。

示例：

这是一个一级标题
========================================================================

这是一个二级标题
------------------------------------------------------------------------

### 这是一个三级标题

你也可以选择在行首加井号表示不同级别的标题 (H1-H6)，例如：# H1, ## H2, ### H3，#### H4。

3. 外链接

使用 [描述](链接地址) 为文字增加外链接。

示例：

这是去往本人博客的链接。

4. 无序列表

使用 *，+，- 表示无序列表。

示例：

无序列表项一
无序列表项二
无序列表项三

5. 有序列表

使用数字和点表示有序列表。

示例：

有序列表项一
有序列表项二
有序列表项三

6. 文字引用

使用 > 表示文字引用。

示例：

野火烧不尽，春风吹又生。

7. 行内代码块

使用 \`代码` 表示行内代码块。

示例：

让我们聊聊 html。

8. 代码块

使用四个缩进空格表示代码块。

示例：

这是一个代码块，此行左侧有四个不可见的空格。

9. 插入图像

使用 \![描述](图片链接地址) 插入图像。

示例：

我的头像

Markdown 高阶语法

1. 内容目录

在段落中填写 [TOC] 以显示全文内容的目录结构。

[TOC]

2. 标签分类

在编辑区任意行的列首位置输入以下代码给文稿标签：

标签：数学英语 Markdown

或者

Tags：数学英语 Markdown

3. 删除线

使用 ~~ 表示删除线。

~~这是一段错误的文本。~~

4. 注脚

使用 ¹ 表示注脚。

这是一个注脚²的样例。

5. LaTeX 公式³

$ 表示行内公式：

质能守恒方程可以用一个很简洁的方程式 $E=mc^2$ 来表达。

$$ 表示整行公式：

$$\sum_{i=1}^n a_i=0$$

$$f(x_1,x_x,\ldots,x_n) = x_1^2 + x_2^2 + \cdots + x_n^2 $$

$$\sum^{j-1}_{k=0}{\widehat{\gamma}_{kj} z_k}$$

6. 加强的代码块⁴

支持四十一种编程语言的语法高亮的显示，行号显示。

非代码示例：

$ sudo apt-get install vim-gnome

Python 示例：

@requires_authorization
def somefunc(param1='', param2=0):
    '''A docstring'''
    if param1 > param2: # interesting
        print 'Greater'
    return (param2 - param1 + 1) or None

class SomeClass:
    pass

>>> message = '''interpreter
... prompt'''

JavaScript 示例：

/**
* nth element in the fibonacci series.
* @param n >= 0
* @return the nth element, >= 0.
*/
function fib(n) {
  var a = 1, b = 1;
  var tmp;
  while (--n >= 0) {
    tmp = a;
    a += b;
    b = tmp;
  }
  return a;
}

document.write(fib(10));

7. 流程图

示例

st=>start: Start:>https://www.zybuluo.com
io=>inputoutput: verification
op=>operation: Your Operation
cond=>condition: Yes or No?
sub=>subroutine: Your Subroutine
e=>end

st->io->op->cond
cond(yes)->e
cond(no)->sub->io

更多语法参考：流程图语法参考

8. 序列图

示例 1

Alice->Bob: Hello Bob, how are you?
Note right of Bob: Bob thinks
Bob-->Alice: I am good thanks!

示例 2

Title: Here is a title
A->B: Normal line
B-->C: Dashed line
C->>D: Open arrow
D-->>A: Dashed open arrow

更多语法参考：序列图语法参考

9. 甘特图

甘特图内在思想简单。基本是一条线条图，横轴表示时间，纵轴表示活动（项目），线条表示在整个期间上计划和实际的活动完成情况。它直观地表明任务计划在什么时候进行，及实际进展与计划要求的对比。

    title 项目开发流程
    section 项目确定
        需求分析       :a1, 2016-06-22, 3d
        可行性报告     :after a1, 5d
        概念验证       : 5d
    section 项目实施
        概要设计      :2016-07-05  , 5d
        详细设计      :2016-07-08, 10d
        编码          :2016-07-15, 10d
        测试          :2016-07-22, 5d
    section 发布验收
        发布: 2d
        验收: 3d

更多语法参考：甘特图语法参考

10. Mermaid 流程图

    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]

更多语法参考：Mermaid 流程图语法参考

11. Mermaid 序列图

    Alice->John: Hello John, how are you?
    loop every minute
        John-->Alice: Great!
    end

更多语法参考：Mermaid 序列图语法参考

12. 表格支持

项目	价格	数量
计算机	$1600	5
手机	$12	12
管线	$1	234

13. 定义型列表

名词 1
: 定义 1（左侧有一个可见的冒号和四个不可见的空格）

代码块 2
: 这是代码块的定义（左侧有一个可见的冒号和四个不可见的空格）

    代码块（左侧有八个不可见的空格）

14. Html 标签

本站支持在 Markdown 语法中嵌套 Html 标签，譬如，你可以用 Html 写一个纵跨两行的表格：

<table>
    <tr>
        <th rowspan="2">值班人员</th>
        <th>星期一</th>
        <th>星期二</th>
        <th>星期三</th>
    </tr>
    <tr>
        <td>李强</td>
        <td>张明</td>
        <td>王平</td>
    </tr>
</table>

值班人员	星期一	星期二	星期三
值班人员	李强	张明	王平

15. 内嵌图标

本站的图标系统对外开放，在文档中输入

<i class="icon-weibo"></i>

即显示微博的图标：

替换上述 i 标签 内的 icon-weibo 以显示不同的图标，例如：

<i class="icon-renren"></i>

即显示人人的图标：

更多的图标和玩法可以参看 font-awesome 官方网站。

16. 待办事宜 Todo 列表

使用带有 [ ] 或 [x] （未完成或已完成）项的列表语法撰写一个待办事宜列表，并且支持子列表嵌套以及混用Markdown语法，例如：

- [ ] **Cmd Markdown 开发**
    - [ ] 改进 Cmd 渲染算法，使用局部渲染技术提高渲染效率
    - [ ] 支持以 PDF 格式导出文稿
    - [x] 新增Todo列表功能 [语法参考](https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments)
    - [x] 改进 LaTex 功能
        - [x] 修复 LaTex 公式渲染问题
        - [x] 新增 LaTex 公式编号功能 [语法参考](http://docs.mathjax.org/en/latest/tex.html#tex-eq-numbers)
- [ ] **七月旅行准备**
    - [ ] 准备邮轮上需要携带的物品
    - [ ] 浏览日本免税店的物品
    - [x] 购买蓝宝石公主号七月一日的船票

对应显示如下待办事宜 Todo 列表：

[ ] Cmd Markdown 开发
- [ ] 改进 Cmd 渲染算法，使用局部渲染技术提高渲染效率
- [ ] 支持以 PDF 格式导出文稿
- [x] 新增Todo列表功能语法参考
- [x] 改进 LaTex 功能
  - [x] 修复 LaTex 公式渲染问题
  - [x] 新增 LaTex 公式编号功能语法参考
[ ] 七月旅行准备
- [ ] 准备邮轮上需要携带的物品
- [ ] 浏览日本免税店的物品
- [x] 购买蓝宝石公主号七月一日的船票

总而言之，不同于其它 所见即所得 的编辑器：你只需使用键盘专注于书写文本内容，就可以生成印刷级的排版格式，省却在键盘和工具栏之间来回切换，调整内容和格式的麻烦。Markdown 在流畅的书写和印刷级的阅读体验之间找到了平衡。

keyword ↩
这是一个注脚的文本。 ↩
支持 LaTeX 编辑显示支持，例如：$\sum_{i=1}^n a_i=0$，访问 MathJax 参考更多使用方法。 ↩
代码高亮功能支持包括 Java, Python, JavaScript 在内的，四十一种主流编程语言。 ↩

Initial主题简要使用指南

作者：Holts 时间：2023年07月02日分类：默认分类字数：5097

主题发布有一段时间了，功能添加的也稍微多了些，由于本人语言表达不是很好🤨可能有些朋友在使用主题时，会有一些困惑，在这里我就把主题在使用过程中可能遇到的问题简单解释一下，如果在看完本文内容还有问题，请留言。

一、文章内设置项
此处为编辑文章时，最下方“自定义字段”位置的选项设置，此处的设置只对当前文章或者页面生效。

文章缩略图
文章缩略图就是在首页或者归档页才会显示的一张展示图片(图片大小无任何限制，请自行控制)。
本主题是一个主打文字的主题，所以默认是不显示文章缩略图的，如果需要显示缩略图，在编辑文章或者页面时，最下方的“自定义字段”位置有一个“自定义缩略图”的选项，可以输入你喜欢的图片的地址来作为该文章的缩略图。如果想要使用文章内的第一张图片作为缩略图，只需输入数字“1”即可（若该文章内无图，则不显示）。

2.3版本更新：文章缩略图支持调用文章内的任意图片。如果想要使用文章内的第三张图片作为缩略图，只需输入数字“3”即可（若该文章内无第三张图片，则不显示）。

文章目录
默认关闭，启用则会在该文章内显示“文章目录”，如果文章内无任何标题，就算此选项已启用，也是不会显示目录的。
注：2.4.5版添加了文章目录的全局开关，所以需要在 “控制台-外观-设置外观-文章目录” 启用 “使用文章内设定” 后，这里的设置才会生效。

二、轻语
轻语是2.3版新出的一项功能，类似于说说，用于发表一些小动态 or 小牢骚 or ...
使用此功能需要先在后台创建独立页面，然后选择“轻语”模板即可（若不想在导航栏显示，可以设置为隐藏）。前台进入此页面，如果是在登录状态下，您就可以在此页面发表“轻语”了。若您想在首页展示你的“轻语”，您可进入后台-控制台-外观设置内找到“显示最新的轻语”选项，勾选对应的位置即可。

注意：

“轻语”支持Markdown语法，默认支持

这几个标签，如果需要支持更多标签，请在后台-设置-评论内找到“允许使用的HTML标签和属性”，添加对应的标签即可。
“轻语”对图片大小无限制（max-width:100%），请自行控制。
管理“轻语”（修改、删除、等操作）请在后台-管理-评论内操作。（“轻语”基于Typecho的评论功能）
目前发布“轻语”的权限设置为（2.4版更新为：具有“编译”以上权限的用户）所有登陆用户，即你的网站内所有已注册用户登陆后都可发表，后续看反馈是否需要调整。
开启“轻语”将强制“将较新的的评论显示在前面”。
有其余问题可随时提问。
三、链接
此项为2.1版本新增的功能，但从2.4版开始，链接列表已从外观设置迁移至管理-独立页面-链接模板页面-自定义字段-links内。
新用户若需要使用“链接”功能，请前往 后台-管理-独立页面-新增页面-自定义模板-选择“链接” 创建“链接”模板页面，然后新增“自定义字段”，字段名称设置为links，字段值按照下方的格式输入即可插入链接。
添加链接
管理链接列表请编辑“链接”模板（后台-管理-独立页面-链接模板页面），在最下方的自定义字段-links内按照以下格式添加即可。
链接输入格式：
链接名称,链接地址,链接描述,链接图标,链接分类不同信息之间用英文逗号“,”分隔，例如：
OFFODD,http://www.offodd.com/,JIElive的博客 | 有点不同,https://www.offodd.com/logo.png,Myself
若中间有暂时不想填的信息，请留空，例如暂时不想填写链接描述和链接图标：
OFFODD,http://www.offodd.com/,,,Myself
若结尾有暂时不想填的信息，无需逗号，可直接留空，例如暂时不想填写链接图标和链接分类：
OFFODD,http://www.offodd.com/,JIElive的博客 | 有点不同
多个链接换行即可，一行一个
小技巧：如果某个链接已经失效，但是又不需要立即删除它，常用场景就是链接站点无法访问或者友链站点把你的友链删除了，你就可以给链接名称加上标签，把链接地址留空，把链接描述改为原因，然后链接地址和链接描述可以放到链接分类后面来备份，例如：
OFFODD,,暂时无法访问,,Myself,备份：http://www.offodd.com/JIElive的博客 | 有点不同https://www.offodd.com/logo.png
11月7日更新：若 链接地址 留空，则自动添加标签
链接功能使用效果可以预览本站的链接页面。
四、后台设置
绝大部分的内容都在这里。
我发现竟然很多人不知道有主题设置或者不知道在哪里，这里说一下，进入后台-控制台-外观-外观设置。
站点标题 LOGO 地址
默认是显示后台设置的站点名称（文字版），此处可以填入你的LOGO图片的地址，填入后就会在站点名称显示的位置显示你填入的LOGO（站点名称不再显示 2.4.5版添加自定义显示），图片高度是限制最高30像素，超出则会缩小到30像素高，宽度不限。
自定义站点标题
仅用于替换页面头部位置的“站点标题”内容，其余tittle()不影响。
站点标题显示内容
2.4.5版新增内容，有不少朋友反应需要LOGO和文字标题同时显示，此处可以自定义。
自定义站点副标题
站点标题就是你使用浏览器浏览网站时，在浏览器上显示的网站名称，默认只显示站点名称，此处可以填入一个你喜欢的副标题，填入后将在原标题后方使用“ - ”分隔符显示你设置的副标题，例如：标题 - 副标题。（副标题仅在首页时显示）
Favicon 地址
Favicon 就是你使用浏览器浏览网站时，在浏览器标题前显示的网站小LOGO，填写一个你的LOGO地址即可。（Favicon建议使用ico格式）
自定义样式
在这里填入你的自定义样式，请直接填入css即可，无需

FastAPI 最佳实践

alembic.ini

FastAPI 开发模板

FastAPI Example Project

Local Development

First Build Only

Linters

Migrations

Tests

Documentation

Waxy 简约自适应博客主题

Waxy 简约自适应博客主题

安装主题

主题功能介绍

短代码

效果

使用方法

代码高亮

自定义侧边栏

自定义CSS/JS

友情链接管理

文章首图

文章标星

文章内容失效提醒

置顶公告&文章

阅读剩余部分

时间线

归档页面

友情链接页面

Sitemap/网站地图

Markdown 简明语法手册

Markdown 简明语法手册

什么是 Markdown

Markdown 语法

1. 斜体和粗体

2. 分级标题

3. 外链接

4. 无序列表

5. 有序列表

6. 文字引用

7. 行内代码块

8. 代码块

9. 插入图像

Markdown 高阶语法

1. 内容目录

2. 标签分类

3. 删除线

4. 注脚

5. LaTeX 公式3

6. 加强的代码块4

7. 流程图

示例

更多语法参考：流程图语法参考

8. 序列图

示例 1

示例 2

更多语法参考：序列图语法参考

9. 甘特图

更多语法参考：甘特图语法参考

10. Mermaid 流程图

更多语法参考：Mermaid 流程图语法参考

11. Mermaid 序列图

更多语法参考：Mermaid 序列图语法参考

12. 表格支持

13. 定义型列表

14. Html 标签

15. 内嵌图标

16. 待办事宜 Todo 列表

Initial主题简要使用指南

5. LaTeX 公式³

6. 加强的代码块⁴