docs(开发日记): 添加python包管理工具uv和springboot logback配置文档

添加两篇开发日记文档： 1. 详细介绍python包管理工具uv的使用指南 2. 提供springboot项目logback配置模板及详细说明
2026-01-18 20:06:57 +08:00
parent b890b18212
commit afe7569729
2 changed files with 580 additions and 0 deletions
--- a/src/content/posts/开发日记/python包管理工具uv使用.md
+++ b/src/content/posts/开发日记/python包管理工具uv使用.md
@@ -0,0 +1,350 @@
+---
+title: 开发日记/python包管理工具uv使用
+published: 2026-01-18T19:23:07
+description: "uv 是一个极速的 Python 包管理和项目管理工具，由 Rust 编写。本文介绍了 uv 的安装、基础用法以及如何使用它来替代 pip、poetry 和 pyenv。"
+image: ""
+
+draft: false
+lang: ""
+category: "开发日记"
+tags:
+  - "python"
+  - "包管理"
+  - "uv"
+  - "rust"
+---
+
+# uv 使用指南
+
+在 Python 的开发生态中，包管理和环境管理一直是一个让人头疼的话题。从 `pip` 到 `pipenv`，再到 `poetry` 和 `pdm`，工具层出不穷。而最近，由 Astral（Ruff 的开发者）推出的 **uv** 横空出世，凭借其**极快的速度**和**全能的特性**，迅速成为了 Python 开发者的新宠。
+
+本文将带你快速上手 uv，体验这个"终结者"级别的工具。
+
+## 什么是 uv？
+
+`uv` 是一个用 Rust 编写的 Python 包安装器和解析器。它的设计初衷是替代 `pip`、`pip-tools` 和 `virtualenv`，但随着版本的迭代，它现在已经具备了替代 `poetry`（项目管理）、`pyenv`（Python 版本管理）和 `pipx`（工具管理）的能力。
+
+**核心特点：**
+
+- **极速**：比 pip 快 10-100 倍。
+- **全能**：一个工具搞定 Python 安装、虚拟环境、依赖管理、工具运行。
+- **兼容**：兼容 `pyproject.toml` 标准。
+
+## 1. 安装 uv
+
+uv 提供了多种安装方式，推荐使用官方的独立安装脚本，这样升级和管理更方便。
+
+### macOS / Linux
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Windows (PowerShell)
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### 使用 pip 安装
+
+如果你只是想尝鲜，也可以通过 pip 安装：
+
+```bash
+pip install uv
+```
+
+安装完成后，可以通过以下命令验证：
+
+```bash
+uv --version
+```
+
+## 2. 项目管理 (Modern Workflow)
+
+这是 uv 目前最推荐的使用方式，类似于 `poetry` 或 `npm` 的体验。
+
+### 初始化项目
+
+```bash
+# 创建一个新项目
+uv init my-project
+cd my-project
+```
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/vvzidl-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/vwl6mu-1.webp)
+
+这将创建一个 `pyproject.toml` 文件和一个 `.python-version` 文件。
+
+### 添加依赖
+
+不再需要手动激活虚拟环境，`uv add` 会自动处理虚拟环境的创建和依赖的安装。
+
+```bash
+# 添加依赖
+uv add requests
+
+# 添加开发依赖 (例如 pytest)
+uv add --dev pytest
+```
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/vwrk27-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/vx4n39-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/vxz3kj-1.webp)
+
+### 配置国内镜像源
+
+#### 配置项目镜像
+
+可以参考这个 `https://uv.oaix.tech/blog/2025/06/17/quickly-set-uv-package-index-is-china-mirror/` 来配置国内镜像源。
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/vygekp-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/vyls9m-1.webp)
+
+在 ` pyproject.toml` 里面添加下面的内容
+
+```toml
+[[tool.uv.index]]
+name = "tencent"
+url = "https://mirrors.cloud.tencent.com/pypi/simple/" # 腾讯云镜像源
+```
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/vz77xi-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w7ixxh-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w7uppx-1.webp)
+
+可以看到里面已经用上镜像了
+
+#### 配置全局镜像源
+
+参考这个 `https://www.cnblogs.com/ljbguanli/p/19357762`
+
+全局配置后，所有项目默认使用指定镜像，无需重复设置。
+
+步骤 1：找到配置文件路径
+
+- Linux/macOS：~/.config/uv/config.toml
+- Windows：%USERPROFILE%\.config\uv\config.toml（如 C:\Users\你的用户名\.config\uv\config.toml）
+
+步骤 2：创建/编辑配置文件
+
+```
+# Linux/macOS：用 vim 打开（若文件不存在会自动创建）
+vim ~/.config/uv/config.toml
+# Windows：用记事本打开
+Write-Host $env:USERPROFILE
+
+
+notepad %USERPROFILE%\.config\uv\config.toml
+```
+
+```toml
+# 阿里云镜像（推荐，稳定性好）
+[registries.pypi]
+index = "https://mirrors.aliyun.com/pypi/simple/"
+```
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w2n47v-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w3acq4-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w3ngws-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w3qyvu-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w47xz8-1.webp)
+
+> 不过网上推荐的都是直接设置环境变量 `UV_DEFAULT_INDEX`
+
+For Linux Users:
+
+```bash
+# 推荐使用清华源
+echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"'>> ~/.bashrc
+
+# 或者用阿里源
+# echo 'export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple/"' >> ~/.bashrc
+
+# 让配置立即生效
+source ~/.bashrc
+```
+
+For Windows Users: 
+
+ 这个只在当前会话生效，关闭会话后就会失效。
+```powershell
+$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
+```
+
+想永久生效就
+![](https://blog.meowrain.cn/api/i/2026/01/18/w63ik2-1.webp)
+
+环境变量不知道去哪儿找可以直接 windows 搜索 `环境变量` 就可以找到。
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w6bb65-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w91iwr-1.webp)
+
+
+
+### 如果是已经有的项目，如何用 uv 同步包呢？
+
+如果是已经有的项目，你可以使用 `uv sync` 命令来同步项目的依赖。
+
+```bash
+uv sync
+```
+
+这将根据 `pyproject.toml` 中的配置，安装所有必要的依赖。
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w06627-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/w0aosh-1.webp)
+
+### 运行代码
+
+使用 `uv run` 可以在项目的虚拟环境中执行命令，无需显式激活环境。
+
+```bash
+# 运行脚本
+uv run main.py
+
+# 运行工具
+uv run pytest
+```
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/wbir6y-1.webp)
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/wbml7j-1.webp)
+
+### 同步环境
+
+如果你拉取了别人的代码，或者手动修改了 `pyproject.toml`，可以使用 `sync` 命令同步环境：
+
+```bash
+uv sync
+```
+
+## 3. Python 版本管理
+
+uv 内置了 Python 版本管理功能，这意味着你不再需要安装 `pyenv` 或 `conda` 来管理不同的 Python 版本。
+
+```bash
+# 列出可用的 Python 版本
+uv python list
+
+# 安装特定版本的 Python
+uv python install 3.12
+
+# 为当前项目指定 Python 版本
+uv python pin 3.11
+```
+
+当你运行 `uv run` 或 `uv sync` 时，uv 会自动下载并使用项目指定的 Python 版本。
+
+这个也可以用镜像，不然走github国内很慢
+很简单
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/x4rjp3-1.webp)
+
+```
+UV_PYTHON_INSTALL_MIRROR
+
+https://mirror.nju.edu.cn/github-release/astral-sh/python-build-standalone/
+```
+
+linux的话 
+```bash
+export UV_PYTHON_INSTALL_MIRROR="https://mirror.nju.edu.cn/github-release/astral-sh/python-build-standalone/"
+```
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/x627ey-1.webp)
+
+## 4. 脚本支持 (Script Support)
+
+uv 对单文件脚本的支持非常出色。你可以在脚本顶部声明依赖，uv 会自动下载并运行，且不会污染全局环境。
+
+创建一个 `example.py`：
+
+```python
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "requests<3",
+#     "rich",
+# ]
+# ///
+
+import requests
+from rich.pretty import pprint
+
+resp = requests.get("https://peps.python.org/api/peps.json")
+data = resp.json()
+pprint([(k, v["title"]) for k, v in data.items()][:10])
+```
+
+直接运行：
+
+```bash
+uv run example.py
+```
+
+uv 会自动解析头部元数据，创建一个临时环境并安装依赖，然后执行脚本。
+
+## 5. 工具管理 (Tool Management)
+
+类似于 `pipx`，uv 可以安装和运行全局的 Python 命令行工具。
+
+```bash
+# 临时运行一个工具 (例如 ruff)
+uvx ruff check .
+# 或者
+uv tool run ruff check .
+
+# 安装一个工具到全局
+uv tool install black
+```
+
+## 6. 兼容 pip 的接口 (Legacy Interface)
+
+如果你不想改变现有的工作流，只想利用 uv 的速度，可以使用它的 pip 兼容接口。
+
+```bash
+# 创建虚拟环境
+uv venv
+
+# 创建指定版本的虚拟环境
+uv venv --python 3.12
+
+# 激活环境 (Windows)
+.venv\Scripts\activate
+# 激活环境 (macOS/Linux)
+source .venv/bin/activate
+
+# 安装依赖 (替代 pip install)
+uv pip install requests
+
+# 从 requirements.txt 安装
+uv pip install -r requirements.txt
+
+# 生成锁定文件 (替代 pip-compile)
+uv pip compile pyproject.toml -o requirements.txt
+```
+
+## 总结
+
+uv 正在以惊人的速度重塑 Python 的开发体验。它不仅解决了"慢"的问题，更重要的是它试图统一碎片化的 Python 工具链。
+
+**迁移建议：**
+
+- **新项目**：直接使用 `uv init` 和 `uv add` 的工作流。
+- **老项目**：可以先用 `uv pip` 替代 `pip` 加速安装，时机成熟后迁移到 `pyproject.toml` 管理。
+- **脚本**：强烈推荐使用 `uv run` 运行带依赖声明的单文件脚本。
+
--- a/src/content/posts/开发日记/springboot项目logback配置.md
+++ b/src/content/posts/开发日记/springboot项目logback配置.md
@@ -0,0 +1,230 @@
+---
+title: 开发日记/springboot项目logback配置
+published: 2026-01-18T19:24:15
+description: ''
+image: 'https://blog.meowrain.cn/api/i/2026/01/18/vuaftq-1.webp'
+
+draft: false 
+lang: ''
+category: '开发日记'
+tags:
+  - 'springboot'
+  - 'logback'
+---
+
+# 文件内容 可通用
+可以直接复制到项目的 `src/main/resources/logback-spring.xml` 文件中。
+
+![](https://blog.meowrain.cn/api/i/2026/01/18/vuaftq-1.webp)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!--debug="false" 表示关闭 Logback 框架自身的内部状态信息打印。-->
+<configuration scan="true" scanPeriod="10 seconds" debug="false">
+    <!--    引入 spring boot 默认日志颜色和基础配置-->
+    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
+    <!--    定义变量 APP_NAME，从 Spring 环境变量中获取 spring.application.name 的值-->
+    <springProperty scope="context" name="APP_NAME" source="spring.application.name"/>
+
+<!--    定义时间格式，yyyy-MM 表示年-月，yyyy-MM-dd 表示年-月-日-->
+    <timestamp key="time-month" datePattern="yyyy-MM"/>
+    <timestamp key="time-month-day" datePattern="yyyy-MM-dd"/>
+    <!--    定义变量 LOG_FILE_PATH，默认值为 ./logs/${APP_NAME}，可以通过环境变量 LOG_PATH 覆盖 日志存储路径-->
+    <property name="LOG_FILE_PATH" value="${LOG_PATH:-./logs/${APP_NAME}}"/>
+    <!--    定义日志格式
+    格式说明：
+    %d{yyyy-MM-dd HH:mm:ss.SSS}：日志记录时间，格式为年-月-日 时:分:秒.毫秒
+    [%thread]：日志记录线程名称
+    %-5level：日志级别，左对齐，占用 5 个字符宽度
+    %logger{50}：日志记录器名称，最多显示 50 个字符
+    -[%X{traceId:-}]：从 MDC 中获取 traceId 变量值，如果不存在则显示为空
+    %msg%n：日志消息内容，换行符
+    -->
+    <property name="FILE_LOG_PATTERN"
+              value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} -[%X{traceId:-}] %msg%n"/>
+
+    <!--    appender 控制台输出-->
+    <!--
+    <appender>: 这是 Logback 配置的根标签之一，用于定义一个日志输出目的地。
+    name="CONSOLE": 为这个 Appender 赋予一个唯一的名称，方便在 <root> 或 <logger> 标签中引用它。
+    class="ch.qos.logback.core.ConsoleAppender": 指定使用的实现类。
+    ConsoleAppender 是 Logback 库中专门用于将日志事件写入 System.out (标准输出) 或 System.err (标准错误) 的类。
+    这是我们在本地开发和测试时最常用的 Appender。
+    CONSOLE_LOG_PATTERN 是上面include的默认日志格式，这里直接引用即可
+    -->
+    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>${CONSOLE_LOG_PATTERN}</pattern>
+            <charset>UTF-8</charset>
+        </encoder>
+    </appender>
+
+    <!--    全量info日志-->
+    <appender name="INFO_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+        <file>${LOG_FILE_PATH}/${time-month}/${time-month-day}/info.log</file>
+        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
+            <fileNamePattern>${LOG_FILE_PATH}/${time-month}/${time-month-day}/info.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
+            <maxFileSize>100MB</maxFileSize>
+            <maxHistory>31</maxHistory>
+            <totalSizeCap>100GB</totalSizeCap>
+        </rollingPolicy>
+        <encoder>
+            <pattern>${FILE_LOG_PATTERN}</pattern>
+            <charset>UTF-8</charset>
+        </encoder>
+        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
+            <!-- 只记录 INFO 级别以及以上的日志的日志 -->
+            <level>INFO</level>
+        </filter>
+    </appender>
+    <appender name="ERROR_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+        <file>${LOG_FILE_PATH}/${time-month}/${time-month-day}/error.log</file>
+        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
+            <fileNamePattern>${LOG_FILE_PATH}/${time-month}/${time-month-day}/error.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
+            <maxFileSize>100MB</maxFileSize>
+            <maxHistory>31</maxHistory>
+            <totalSizeCap>100GB</totalSizeCap>
+        </rollingPolicy>
+        <encoder>
+            <pattern>${FILE_LOG_PATTERN}</pattern>
+            <charset>UTF-8</charset>
+        </encoder>
+        <filter class="ch.qos.logback.classic.filter.LevelFilter">
+            <!-- 只记录 ERROR 级别以及以上的日志的日志 -->
+            <level>ERROR</level>
+            <onMatch>ACCEPT</onMatch>
+            <onMismatch>DENY</onMismatch>
+        </filter>
+    </appender>
+
+    <!--    异步写入日志-->
+    <appender name="ASYNC_INFO"
+              class="ch.qos.logback.classic.AsyncAppender">
+        <discardingThreshold>0</discardingThreshold>
+        <queueSize>512</queueSize>
+        <appender-ref ref="INFO_FILE"/>
+    </appender>
+    <appender name="ASYNC_ERROR" class="ch.qos.logback.classic.AsyncAppender">
+        <discardingThreshold>0</discardingThreshold>
+        <queueSize>512</queueSize>
+        <appender-ref ref="ERROR_FILE"/>
+    </appender>
+
+
+    <!--    =========== 环境配置 打印到控制台 ===========-->
+    <springProfile name="dev">
+        <root level="INFO">
+            <appender-ref ref="CONSOLE"/>
+            <appender-ref ref="ASYNC_ERROR"/>
+            <appender-ref ref="ASYNC_INFO"/>
+        </root>
+    </springProfile>
+
+    <springProfile name="prod">
+        <root level="INFO">
+            <appender-ref ref="CONSOLE"/>
+            <appender-ref ref="ASYNC_ERROR"/>
+            <appender-ref ref="ASYNC_INFO"/>
+        </root>
+    </springProfile>
+</configuration>
+```
+
+## 配置详解
+
+### 1. 根节点配置 (`<configuration>`)
+
+```xml
+<configuration scan="true" scanPeriod="10 seconds" debug="false">
+```
+
+*   **scan="true"**: 配置文件如果发生改变，将会被重新加载。
+*   **scanPeriod="10 seconds"**: 监测配置文件是否有修改的时间间隔，默认单位是毫秒。
+*   **debug="false"**: 关闭 Logback 框架自身的内部状态信息打印，设置为 `true` 时可以在控制台看到 Logback 的加载过程，有助于排查 Logback 配置错误。
+
+### 2. 基础引用与变量定义
+
+#### 引入 Spring Boot 默认配置
+```xml
+<include resource="org/springframework/boot/logging/logback/defaults.xml"/>
+```
+这行代码引入了 Spring Boot 预定义的日志配置，包含了控制台输出的彩色日志格式 `CONSOLE_LOG_PATTERN` 等常用变量。
+
+#### 获取 Spring 配置属性
+```xml
+<springProperty scope="context" name="APP_NAME" source="spring.application.name"/>
+```
+*   `<springProperty>`: 允许从 Spring 的 `Environment` 中读取属性并暴露给 Logback。
+*   这里读取了 `spring.application.name`（应用名称）赋值给变量 `APP_NAME`，用于后续生成日志文件路径。
+
+#### 定义时间戳变量
+```xml
+<timestamp key="time-month" datePattern="yyyy-MM"/>
+<timestamp key="time-month-day" datePattern="yyyy-MM-dd"/>
+```
+定义了两个时间戳变量，用于构建按月或按天归档的目录结构。
+
+#### 定义日志路径
+```xml
+<property name="LOG_FILE_PATH" value="${LOG_PATH:-./logs/${APP_NAME}}"/>
+```
+*   `${LOG_PATH:-./logs/${APP_NAME}}`: 这是一个默认值语法。如果环境变量 `LOG_PATH` 存在，则使用它；否则使用 `./logs/${APP_NAME}`。
+
+### 3. 日志格式 (`FILE_LOG_PATTERN`)
+
+```xml
+<property name="FILE_LOG_PATTERN"
+          value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} -[%X{traceId:-}] %msg%n"/>
+```
+*   `%d`: 日期时间。
+*   `[%thread]`: 线程名。
+*   `%-5level`: 日志级别（左对齐，5字符宽）。
+*   `%logger{50}`: 类名（最大长度50，超长会智能缩写）。
+*   `[%X{traceId:-}]`: 这是一个 MDC (Mapped Diagnostic Context) 变量。用于分布式链路追踪，如果 MDC 中有 `traceId` 则显示，否则显示 `-`。
+*   `%msg`: 日志具体内容。
+*   `%n`: 换行。
+
+### 4. 输出源 (Appenders)
+
+#### 控制台输出 (`CONSOLE`)
+使用 `ConsoleAppender` 将日志输出到标准输出，并直接复用了 Spring Boot 默认的 `CONSOLE_LOG_PATTERN`。
+
+#### 滚动文件输出 (`INFO_FILE` / `ERROR_FILE`)
+使用 `RollingFileAppender` 实现日志文件的滚动策略。
+
+*   **滚动策略 (`SizeAndTimeBasedRollingPolicy`)**:
+    *   **按时间滚动**: 每天生成一个新的日志文件 (`%d{yyyy-MM-dd}`).
+    *   **按大小滚动**: 如果单天日志超过 `100MB` (`%i`)，会切分出新文件。
+    *   **历史保留**: `<maxHistory>31</maxHistory>` 保留最近 31 天的日志。
+    *   **总大小限制**: `<totalSizeCap>100GB</totalSizeCap>` 限制所有日志文件总大小不超过 100GB。
+
+*   **过滤器 (Filter)**:
+    *   `INFO_FILE` 使用 `ThresholdFilter`: 记录 `INFO` 及以上级别（INFO, WARN, ERROR）。
+    *   `ERROR_FILE` 使用 `LevelFilter`: **只**记录 `ERROR` 级别。
+        *   `onMatch=ACCEPT`: 匹配 ERROR 则记录。
+        *   `onMismatch=DENY`: 不匹配则丢弃。
+
+### 5. 异步处理 (`AsyncAppender`)
+
+```xml
+<appender name="ASYNC_INFO" class="ch.qos.logback.classic.AsyncAppender">
+    <discardingThreshold>0</discardingThreshold>
+    <queueSize>512</queueSize>
+    <appender-ref ref="INFO_FILE"/>
+</appender>
+```
+*   **作用**: 将日志写入操作放入独立线程执行，避免高并发下 IO 操作阻塞业务线程，提高应用性能。
+*   **queueSize**: 异步队列深度，默认为 256，这里调整为 512。
+*   **discardingThreshold**: 默认为队列剩余 20% 容量时丢弃 TRACE/DEBUG/INFO 日志。设置为 `0` 表示**不丢弃任何日志**，即使队列满了也阻塞等待，保证日志不丢失。
+
+### 6. 环境隔离 (`<springProfile>`)
+
+```xml
+<springProfile name="dev"> ... </springProfile>
+<springProfile name="prod"> ... </springProfile>
+```
+Logback 支持 Spring 的 Profile 功能。
+*   当 `spring.profiles.active=dev` 时，激活 dev 块内的配置。
+*   当 `spring.profiles.active=prod` 时，激活 prod 块内的配置。
+
+当前配置中，`dev` 和 `prod` 都输出了 `CONSOLE`、`ASYNC_ERROR` 和 `ASYNC_INFO`，在实际生产环境中，通常会移除 `CONSOLE` Appender 以减少不必要的控制台输出性能损耗。