深入解析Black项目的HTTP服务模式：blackd使用指南-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00238/article/details/148325739

深入解析Black项目的HTTP服务模式：blackd使用指南

black The uncompromising Python code formatter 项目地址: https://gitcode.com/gh_mirrors/bl/black

什么是blackd

blackd是Python代码格式化工具Black提供的轻量级HTTP服务，它通过简单的HTTP协议暴露Black的核心格式化功能。与直接调用Black命令行工具相比，blackd的主要优势在于避免了每次格式化代码时都需要启动新进程的开销，特别适合需要频繁格式化代码的场景。

安全须知

重要安全提示：blackd设计初衷仅用于本地开发环境，不应作为公开可访问的服务运行。因为它没有内置任何防止滥用的安全措施，直接暴露在公网可能带来安全风险。

安装与基础使用

安装步骤

blackd作为Black的可选组件，需要单独安装：

pip install 'black[d]'

启动服务

启动blackd非常简单，只需在终端运行：

blackd

服务默认绑定到本地回环地址(127.0.0.1)，使用随机可用端口。启动后会显示版本信息和监听地址。

测试服务

虽然blackd没有官方客户端工具，但可以使用curl进行测试：

blackd --bind-port 9090 &  # 指定端口启动
curl -s -XPOST "localhost:9090" -d "print('valid')"

服务配置选项

blackd提供的配置选项比Black命令行工具更精简，可通过blackd --help查看全部选项。主要配置包括：

--bind-host: 指定监听主机地址
--bind-port: 指定监听端口
--version: 显示版本信息

HTTP协议规范

请求规范

blackd只接受POST请求，请求路径固定为/。请求体应包含待格式化的Python源代码。

编码处理：

通过Content-Type头的charset参数指定编码
未指定时默认使用UTF-8编码

控制头信息

通过HTTP头可以控制格式化行为，这些头对应Black的命令行参数：

| HTTP头 | 对应参数 | 说明 | |--------|----------|------| | X-Line-Length | --line-length | 设置行长度限制 | | X-Skip-Source-First-Line | --skip-source-first-line | 跳过源代码首行 | | X-Skip-String-Normalization | --skip-string-normalization | 禁用字符串规范化 | | X-Skip-Magic-Trailing-Comma | --skip-magic-trailing-comma | 禁用尾部逗号换行 | | X-Preview | --preview | 启用预览功能 | | X-Unstable | --unstable | 启用不稳定功能 | | X-Enable-Unstable-Feature | --enable-unstable-feature | 启用特定不稳定功能 | | X-Fast-Or-Safe | --fast | 快速模式 | | X-Python-Variant | --pyi | 处理.pyi文件 | | X-Diff | --diff | 输出差异 |

版本控制：必须包含X-Protocol-Version: 1头，否则返回501错误。