## uv 

```js
uv init [name]
uv venv
uv add [package]
uv sync
```



# uv 使用方法整理

> 适用工具：Astral `uv`  
> 定位：Python 包管理、虚拟环境、Python 版本、项目依赖与脚本运行工具。  
> 适合替代或覆盖 `pip`、`venv`、`virtualenv`、`pip-tools`、部分 `poetry` / `pyenv` 使用场景。

---

## 1. uv 是什么

`uv` 是 Astral 推出的 Python 包和项目管理工具，使用 Rust 编写，特点是：

- 安装和解析依赖速度快
- 自动管理项目虚拟环境
- 使用 `pyproject.toml` 管理项目依赖
- 使用 `uv.lock` 锁定依赖版本
- 可以安装和管理 Python 版本
- 支持类似 `pip` 的命令
- 支持直接运行 Python 脚本和 CLI 工具

如果是新项目，推荐优先使用：

```bash
uv init
uv add
uv remove
uv sync
uv run
```

如果是已有的传统 `requirements.txt` 项目，可以使用：

```bash
uv venv
uv pip install
uv pip sync
uv pip freeze
```

---

# 2. 安装 uv

## 2.1 Windows PowerShell

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

安装完成后检查：

```powershell
uv --version
```

如果提示找不到 `uv`，重新打开终端后再执行。

---

## 2.2 macOS / Linux

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

检查：

```bash
uv --version
```

---

## 2.3 使用 pip 安装

如果已经有 Python，也可以：

```bash
pip install uv
```

不过日常使用更推荐官方独立安装方式，因为 `uv` 本身并不依赖 Python 才能运行。

---

# 3. 最常用工作流

新建一个 Python 项目：

```bash
uv init my-project
cd my-project
```

添加依赖：

```bash
uv add requests
```

添加开发依赖：

```bash
uv add --dev pytest
```

运行 Python：

```bash
uv run python main.py
```

同步项目依赖：

```bash
uv sync
```

移除依赖：

```bash
uv remove requests
```

这基本就是日常开发最常用的一套命令。

---

# 4. 创建项目

## 4.1 创建新项目

```bash
uv init my-project
```

进入项目：

```bash
cd my-project
```

也可以直接在当前目录初始化：

```bash
uv init
```

---

## 4.2 创建普通应用

```bash
uv init my-app
```

较新的 uv 版本默认会为应用项目配置现代 Python 项目结构。

---

## 4.3 创建 Python 库

```bash
uv init --lib my-lib
```

适合：

- Python SDK
- 公共工具包
- 可发布到 PyPI 的库

---

## 4.4 创建最简单项目

如果只是想写一些脚本，不需要打包：

```bash
uv init --no-package
```

或者：

```bash
uv init --bare
```

---

# 5. 项目中常见文件

典型项目中会看到：

```text
my-project/
├─ .venv/
├─ .python-version
├─ pyproject.toml
├─ uv.lock
├─ README.md
└─ src/
```

主要作用：

| 文件 | 作用 |
|---|---|
| `pyproject.toml` | 项目配置、Python 版本、依赖声明 |
| `uv.lock` | 锁定精确依赖版本 |
| `.python-version` | 指定项目 Python 版本 |
| `.venv` | 项目虚拟环境 |
| `src/` | 项目源代码 |

---

# 6. Python 版本管理

`uv` 可以直接安装和管理 Python。

## 6.1 查看 Python

```bash
uv python list
```

---

## 6.2 安装 Python

例如安装 Python 3.12：

```bash
uv python install 3.12
```

安装 Python 3.13：

```bash
uv python install 3.13
```

---

## 6.3 给项目固定 Python 版本

```bash
uv python pin 3.12
```

会生成或更新：

```text
.python-version
```

之后该项目会优先使用指定版本。

---

## 6.4 查找 Python

```bash
uv python find
```

指定版本：

```bash
uv python find 3.12
```

---

## 6.5 卸载 Python

```bash
uv python uninstall 3.12
```

---

# 7. 虚拟环境

## 7.1 创建虚拟环境

```bash
uv venv
```

默认创建：

```text
.venv
```

指定 Python：

```bash
uv venv --python 3.12
```

---

## 7.2 Windows 激活虚拟环境

PowerShell：

```powershell
.venv\Scripts\Activate.ps1
```

CMD：

```cmd
.venv\Scripts\activate.bat
```

---

## 7.3 macOS / Linux 激活

```bash
source .venv/bin/activate
```

---

## 7.4 是否一定要手动激活？

使用现代 uv 项目模式时，通常不需要。

例如：

```bash
uv run python main.py
```

`uv run` 会自动使用项目对应的环境。

所以相比：

```bash
.venv\Scripts\Activate.ps1
python main.py
```

更推荐：

```bash
uv run python main.py
```

---

# 8. 安装项目依赖

## 8.1 添加依赖

例如：

```bash
uv add requests
```

多个依赖：

```bash
uv add requests pandas numpy
```

指定版本：

```bash
uv add "requests==2.32.5"
```

指定最低版本：

```bash
uv add "fastapi>=0.115"
```

---

## 8.2 添加开发依赖

```bash
uv add --dev pytest
```

例如：

```bash
uv add --dev pytest ruff mypy
```

开发依赖通常用于：

- pytest
- ruff
- mypy
- black
- coverage

---

## 8.3 删除依赖

```bash
uv remove requests
```

删除开发依赖同样使用：

```bash
uv remove pytest
```

---

# 9. uv sync

`uv sync` 用来让本地虚拟环境与项目配置、锁文件保持一致。

```bash
uv sync
```

典型场景：

从 Git 拉下项目：

```bash
git clone xxx
cd project
uv sync
```

即可根据：

```text
pyproject.toml
uv.lock
```

创建并同步项目环境。

通常不需要再：

```bash
pip install -r requirements.txt
```

---

# 10. uv.lock

执行：

```bash
uv add xxx
```

或者：

```bash
uv lock
```

会生成：

```text
uv.lock
```

它记录解析后的依赖版本。

建议项目中提交：

```text
pyproject.toml
uv.lock
```

到 Git。

例如：

```bash
git add pyproject.toml uv.lock
git commit -m "update dependencies"
```

---

# 11. uv run

这是 uv 非常常用的命令。

## 11.1 运行 Python 文件

```bash
uv run python main.py
```

---

## 11.2 运行 Python 模块

```bash
uv run python -m pytest
```

---

## 11.3 运行项目里的工具

例如项目安装了：

```bash
uv add --dev pytest
```

直接：

```bash
uv run pytest
```

无需手动激活 `.venv`。

---

## 11.4 运行 FastAPI

安装：

```bash
uv add fastapi uvicorn
```

运行：

```bash
uv run uvicorn main:app --reload
```

---

## 11.5 运行 Django

```bash
uv run python manage.py runserver
```

---

# 12. uv pip

`uv pip` 提供类似传统 `pip` 的低层接口。

适合：

- 老项目
- `requirements.txt` 项目
- 暂时不想改成 `pyproject.toml`
- 希望直接替换部分 pip 工作流

注意：

> `uv pip` 并不是内部调用 pip，而是 uv 自己实现的一套兼容接口。

---

## 12.1 安装包

先创建环境：

```bash
uv venv
```

然后：

```bash
uv pip install requests
```

安装多个：

```bash
uv pip install requests flask pandas
```

---

## 12.2 安装 requirements.txt

```bash
uv pip install -r requirements.txt
```

---

## 12.3 卸载包

```bash
uv pip uninstall requests
```

---

## 12.4 查看已安装包

```bash
uv pip list
```

---

## 12.5 查看包信息

```bash
uv pip show requests
```

---

## 12.6 查看依赖树

```bash
uv pip tree
```

---

## 12.7 导出类似 requirements.txt 的列表

```bash
uv pip freeze
```

保存：

### PowerShell

```powershell
uv pip freeze > requirements.txt
```

### Linux / macOS

```bash
uv pip freeze > requirements.txt
```

---

## 12.8 检查依赖冲突

```bash
uv pip check
```

---

# 13. uv pip sync

假设项目有：

```text
requirements.txt
```

执行：

```bash
uv pip sync requirements.txt
```

它会让当前环境严格与 `requirements.txt` 保持一致。

与：

```bash
uv pip install -r requirements.txt
```

区别可以简单理解为：

```text
install = 安装文件里缺少的依赖
sync    = 把环境同步成文件描述的状态
```

如果环境里存在 requirements 中没有的包，`sync` 可能将其移除。

因此 CI、部署、可复现环境中，`sync` 更合适。

---

# 14. requirements.in 工作流

传统 `pip-tools` 用户可以使用：

```bash
uv pip compile requirements.in -o requirements.txt
```

例如 `requirements.in`：

```text
fastapi
uvicorn
requests
```

生成：

```text
requirements.txt
```

再同步：

```bash
uv pip sync requirements.txt
```

---

# 15. pyproject.toml

例如：

```toml
[project]
name = "demo"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115",
    "requests>=2.32",
]
```

使用：

```bash
uv sync
```

安装依赖。

通常不建议手工维护复杂依赖版本，优先：

```bash
uv add fastapi
uv add requests
```

由 uv 自动修改 `pyproject.toml`。

---

# 16. 指定 Python 版本运行

例如：

```bash
uv run --python 3.12 python main.py
```

或者先：

```bash
uv python pin 3.12
```

再：

```bash
uv run python main.py
```

---

# 17. 临时安装依赖运行

如果只想临时运行，不想把依赖加入项目：

```bash
uv run --with requests python test.py
```

多个临时依赖：

```bash
uv run --with requests --with pandas python test.py
```

适合临时脚本和测试。

---

# 18. uv tool

`uv tool` 可以运行或安装 Python CLI 工具，类似 `pipx`。

## 18.1 临时运行工具

例如 Ruff：

```bash
uvx ruff check .
```

`uvx` 可以理解为：

```bash
uv tool run
```

---

## 18.2 安装全局工具

```bash
uv tool install ruff
```

之后：

```bash
ruff check .
```

---

## 18.3 查看工具

```bash
uv tool list
```

---

## 18.4 卸载工具

```bash
uv tool uninstall ruff
```

---

# 19. 常用命令速查

| 需求 | 命令 |
|---|---|
| 查看版本 | `uv --version` |
| 初始化项目 | `uv init` |
| 新建项目 | `uv init demo` |
| 创建库 | `uv init --lib demo` |
| 创建虚拟环境 | `uv venv` |
| 安装 Python | `uv python install 3.12` |
| 查看 Python | `uv python list` |
| 固定 Python | `uv python pin 3.12` |
| 添加依赖 | `uv add requests` |
| 添加开发依赖 | `uv add --dev pytest` |
| 删除依赖 | `uv remove requests` |
| 同步项目 | `uv sync` |
| 更新锁文件 | `uv lock` |
| 运行 Python | `uv run python main.py` |
| 运行 pytest | `uv run pytest` |
| pip 模式安装 | `uv pip install requests` |
| 安装 requirements | `uv pip install -r requirements.txt` |
| 同步 requirements | `uv pip sync requirements.txt` |
| 查看安装包 | `uv pip list` |
| 查看依赖树 | `uv pip tree` |
| 导出包列表 | `uv pip freeze` |
| 检查依赖 | `uv pip check` |
| 临时运行工具 | `uvx ruff check .` |

---

# 20. pip 与 uv 命令对照

| pip / Python | uv |
|---|---|
| `python -m venv .venv` | `uv venv` |
| `pip install requests` | `uv pip install requests` |
| `pip uninstall requests` | `uv pip uninstall requests` |
| `pip list` | `uv pip list` |
| `pip freeze` | `uv pip freeze` |
| `pip install -r requirements.txt` | `uv pip install -r requirements.txt` |
| `pipx run ruff` | `uvx ruff` |

如果使用 uv 项目模式，更推荐：

| 传统方式 | uv 项目模式 |
|---|---|
| 修改 requirements | `uv add xxx` |
| 删除 requirements 中依赖 | `uv remove xxx` |
| pip install | `uv sync` |
| 激活环境后运行 | `uv run xxx` |

---

# 21. 推荐的新项目开发流程

## 第一步：创建项目

```bash
uv init my-api
cd my-api
```

## 第二步：固定 Python

```bash
uv python pin 3.12
```

如果本机没有：

```bash
uv python install 3.12
```

## 第三步：添加依赖

```bash
uv add fastapi uvicorn
```

## 第四步：添加开发依赖

```bash
uv add --dev pytest ruff
```

## 第五步：开发

```bash
uv run uvicorn main:app --reload
```

## 第六步：测试

```bash
uv run pytest
```

## 第七步：代码检查

```bash
uv run ruff check .
```

---

# 22. 已有项目迁移到 uv

如果老项目只有：

```text
requirements.txt
```

有两种方案。

## 方案一：先不改项目结构

最简单：

```bash
uv venv
uv pip install -r requirements.txt
```

运行：

```bash
uv run python main.py
```

这种迁移风险最低。

---

## 方案二：迁移为 uv 项目

初始化：

```bash
uv init
```

然后把项目依赖逐步加入：

```bash
uv add fastapi
uv add requests
uv add pandas
```

最终依赖由：

```text
pyproject.toml
uv.lock
```

管理。

推荐新项目和长期维护项目使用这种方式。

---

# 23. Git 项目推荐提交内容

推荐提交：

```text
pyproject.toml
uv.lock
.python-version
src/
README.md
```

通常不要提交：

```text
.venv/
```

`.gitignore`：

```gitignore
.venv/
__pycache__/
*.pyc
.pytest_cache/
.ruff_cache/
```

---

# 24. 常见问题

## 24.1 `uv` 不是内部或外部命令

Windows 安装之后如果出现：

```text
uv : 无法将“uv”项识别为 cmdlet...
```

先：

1. 关闭当前 PowerShell
2. 重新打开终端
3. 执行：

```powershell
uv --version
```

仍然不行，再检查安装目录是否已经加入 `PATH`。

---

## 24.2 不想激活虚拟环境怎么办？

直接：

```bash
uv run python main.py
```

或者：

```bash
uv run pytest
```

这是 uv 推荐的项目使用方式之一。

---

## 24.3 uv pip install 提示找不到虚拟环境

先执行：

```bash
uv venv
```

再：

```bash
uv pip install requests
```

`uv pip install` 默认倾向于向虚拟环境安装，而不是直接污染系统 Python。

---

## 24.4 `uv add` 和 `uv pip install` 有什么区别？

### `uv add`

```bash
uv add requests
```

属于项目管理方式。

它会维护：

```text
pyproject.toml
uv.lock
.venv
```

适合正式项目。

### `uv pip install`

```bash
uv pip install requests
```

更接近传统 pip，只对环境进行包安装操作。

适合：

- 老项目
- 临时环境
- requirements.txt 项目

新项目优先：

```bash
uv add
```

---

## 24.5 `uv sync` 和 `uv pip sync` 区别

### 项目模式

```bash
uv sync
```

依据：

```text
pyproject.toml
uv.lock
```

同步。

### pip 兼容模式

```bash
uv pip sync requirements.txt
```

依据：

```text
requirements.txt
```

同步。

---

# 25. Windows PowerShell 推荐流程

如果你主要在 Windows 开发，可以直接记这一套。

## 新项目

```powershell
uv init demo
cd demo

uv python pin 3.12

uv add fastapi uvicorn
uv add --dev pytest ruff

uv run python main.py
```

---

## 已有 requirements.txt 项目

```powershell
cd existing-project

uv venv

uv pip install -r requirements.txt

uv run python main.py
```

---

## FastAPI 项目

```powershell
uv init my-api
cd my-api

uv add fastapi uvicorn

uv run uvicorn main:app --reload
```

---

# 26. 最推荐记住的 8 个命令

如果不想记太多，先记住：

```bash
uv init
uv python pin 3.12
uv add xxx
uv remove xxx
uv sync
uv run xxx
uv venv
uv pip install xxx
```

其中现代项目最核心的是：

```text
uv init
   ↓
uv add
   ↓
uv sync
   ↓
uv run
```

---

# 27. 建议

### 新 Python 项目

推荐：

```text
pyproject.toml + uv.lock + uv add + uv sync + uv run
```

### 老项目

先用：

```text
uv venv + uv pip install -r requirements.txt
```

稳定后再考虑迁移。

### 不建议

在同一个项目里长期混合：

```text
pip install
uv pip install
uv add
poetry add
```

最好固定一种依赖管理方式，否则项目依赖状态容易混乱。

---

# 28. 官方资料

- uv 官方文档：`https://docs.astral.sh/uv/`
- 项目管理：`https://docs.astral.sh/uv/guides/projects/`
- pip 兼容接口：`https://docs.astral.sh/uv/pip/`
- CLI 命令参考：`https://docs.astral.sh/uv/reference/cli/`
- GitHub：`https://github.com/astral-sh/uv`

---

# 29. 一句话总结

传统 Python：

```text
安装 Python
→ 创建 venv
→ 激活环境
→ pip install
→ requirements.txt
→ python main.py
```

使用 uv：

```text
uv python install
→ uv init
→ uv add
→ uv sync
→ uv run
```

对于新项目，可以把 uv 理解成：

> **Python 版本管理 + 虚拟环境 + pip + requirements/lock + 项目运行工具的一体化方案。**

## 创建expo项目（https://docs.expo.dev/more/create-expo/#--template）

```js
npx create-expo-app@latest 

--template
default	默认模板。专为构建多屏应用而设计。包含推荐工具，例如 Expo CLI、Expo Router 库，
        并已启用TypeScript 配置。适用于大多数应用。
blank   安装最少所需的 npm 依赖项，而不配置导航。
blank-typescript	启用 TypeScript 的空白模板。
tabs	  安装并配置基于文件的路由，启用 Expo Router 和 TypeScript。
bare-minimum	 生成包含原生目录（ android和ios ）的空白模板。npx expo prebuild在安装过程中运行。



启动
npx expo start




```

## 打包项目（https://docs.expo.dev/build/setup/）

```js
npm install --global eas-cli
eas login
eas build:configure
eas build --platform android

```

expo

## 集群架构




![image.png](/static/img/e09494fc6bf0db4cbc8ba0ac998626ef.image.webp)

## 分布式

![image.png](/static/img/7f251b4da075af500019512b05c85358.image.webp)

![image.png](/static/img/c6f28aa2c15f1e1a89c98ac239f4fd04.image.webp)

## nacos

![image.png](/static/img/86a779b33965166ecef204a9c5e2504a.image.webp)

# 1. OpenFeign 是什么

OpenFeign 是 Spring Cloud 提供的声明式 HTTP 客户端。

它可以通过定义 Java 接口和注解的方式，直接调用其他服务提供的 HTTP 接口，不需要手动编写 HTTP 请求代码。

例如传统方式可能需要：

```java
RestTemplate restTemplate = new RestTemplate();

User user = restTemplate.getForObject(
    "http://user-service/user/1",
    User.class
);
```

使用 OpenFeign 后，只需要定义接口：

```java
@FeignClient(name = "user-service")
public interface UserClient {

    @GetMapping("/user/{id}")
    User getUser(@PathVariable("id") Long id);
}
```

调用时：

```java
User user = userClient.getUser(1L);
```

OpenFeign 会自动发送 HTTP 请求。

---

# 2. 常见使用场景

OpenFeign 一般用于微服务之间的接口调用。

例如：

```text
订单服务
    ↓
调用用户服务

order-service
    ↓ OpenFeign
user-service
```

订单服务需要获取用户信息时，可以直接通过 FeignClient 调用用户服务。

适合：

- 微服务内部接口调用
- Spring Cloud 项目
- 服务注册中心环境
- REST API 调用
- 对第三方 HTTP API 进行统一封装

---

# 3. 引入依赖

Spring Boot / Spring Cloud 项目中引入：

```xml
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>
```

一般建议 Spring Boot 与 Spring Cloud 使用对应的兼容版本。

---

# 4. 开启 OpenFeign

在 Spring Boot 启动类中添加：

```java
@EnableFeignClients
@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

核心注解：

```java
@EnableFeignClients
```

作用：

扫描项目中的 `@FeignClient` 接口，并创建对应的代理对象。

---

# 5. 创建 FeignClient

例如需要调用用户服务：

```java
@FeignClient(name = "user-service")
public interface UserFeignClient {

    @GetMapping("/user/{id}")
    UserDTO getUserById(@PathVariable("id") Long id);
}
```

调用：

```java
@Service
public class OrderService {

    private final UserFeignClient userFeignClient;

    public OrderService(UserFeignClient userFeignClient) {
        this.userFeignClient = userFeignClient;
    }

    public UserDTO getUser(Long userId) {
        return userFeignClient.getUserById(userId);
    }
}
```

---

# 6. @FeignClient 常用参数

基本写法：

```java
@FeignClient(name = "user-service")
```

## name

表示服务名称。

例如：

```java
@FeignClient(name = "user-service")
```

如果项目接入 Nacos、Eureka 等注册中心：

```text
user-service
```

会对应注册中心里的服务名称。

OpenFeign 会根据服务名找到对应服务实例。

---

## url

如果不是通过注册中心调用，而是直接调用固定地址，可以使用：

```java
@FeignClient(
    name = "userClient",
    url = "http://localhost:8081"
)
```

例如：

```java
@FeignClient(
    name = "weatherClient",
    url = "https://api.example.com"
)
public interface WeatherClient {

    @GetMapping("/weather")
    String getWeather();
}
```

---

## path

可以统一配置接口前缀：

```java
@FeignClient(
    name = "user-service",
    path = "/api/user"
)
public interface UserFeignClient {

    @GetMapping("/{id}")
    UserDTO getUser(@PathVariable("id") Long id);
}
```

最终请求：

```text
/api/user/1
```

---

## configuration

可以为指定 FeignClient 配置单独的配置类：

```java
@FeignClient(
    name = "user-service",
    configuration = FeignConfig.class
)
```

例如配置：

- 请求拦截器
- 日志级别
- Encoder
- Decoder
- ErrorDecoder

---

# 7. GET 请求

## Path 参数

接口：

```http
GET /user/1001
```

Feign：

```java
@GetMapping("/user/{id}")
UserDTO getUser(
    @PathVariable("id") Long id
);
```

调用：

```java
userFeignClient.getUser(1001L);
```

---

## Query 参数

接口：

```http
GET /user/list?page=1&size=20
```

Feign：

```java
@GetMapping("/user/list")
List<UserDTO> listUser(
    @RequestParam("page") Integer page,
    @RequestParam("size") Integer size
);
```

调用：

```java
userFeignClient.listUser(1, 20);
```

---

# 8. POST 请求

## JSON 请求体

接口：

```http
POST /user
Content-Type: application/json
```

请求体：

```json
{
  "name": "张三",
  "age": 20
}
```

Feign：

```java
@PostMapping("/user")
UserDTO createUser(
    @RequestBody CreateUserDTO dto
);
```

调用：

```java
CreateUserDTO dto = new CreateUserDTO();

dto.setName("张三");
dto.setAge(20);

UserDTO user = userFeignClient.createUser(dto);
```

---

# 9. PUT 请求

```java
@PutMapping("/user/{id}")
UserDTO updateUser(
    @PathVariable("id") Long id,
    @RequestBody UpdateUserDTO dto
);
```

调用：

```java
userFeignClient.updateUser(1L, dto);
```

---

# 10. DELETE 请求

```java
@DeleteMapping("/user/{id}")
void deleteUser(
    @PathVariable("id") Long id
);
```

调用：

```java
userFeignClient.deleteUser(1L);
```

---

# 11. 请求头 Header

如果接口需要 Token：

```java
@GetMapping("/user/info")
UserDTO getUserInfo(
    @RequestHeader("Authorization") String token
);
```

调用：

```java
userFeignClient.getUserInfo(
    "Bearer xxx"
);
```

如果每个接口都要传 Token，不建议每个方法都写 `@RequestHeader`。

更推荐使用 RequestInterceptor。

---

# 12. Feign 请求拦截器

创建配置：

```java
@Configuration
public class FeignConfig {

    @Bean
    public RequestInterceptor requestInterceptor() {

        return requestTemplate -> {

            requestTemplate.header(
                "Authorization",
                "Bearer xxx"
            );
        };
    }
}
```

FeignClient：

```java
@FeignClient(
    name = "user-service",
    configuration = FeignConfig.class
)
public interface UserFeignClient {
}
```

这样每个请求都会自动添加：

```http
Authorization: Bearer xxx
```

适合统一添加：

- Authorization
- Token
- TenantId
- UserId
- TraceId
- ClientId

等请求头。

---

# 13. 传递当前请求 Token

微服务中经常需要把当前用户 Token 继续传给下游服务。

例如：

```java
@Bean
public RequestInterceptor requestInterceptor() {

    return requestTemplate -> {

        ServletRequestAttributes attributes =
            (ServletRequestAttributes)
                RequestContextHolder.getRequestAttributes();

        if (attributes == null) {
            return;
        }

        HttpServletRequest request =
            attributes.getRequest();

        String authorization =
            request.getHeader("Authorization");

        if (authorization != null) {
            requestTemplate.header(
                "Authorization",
                authorization
            );
        }
    };
}
```

请求链：

```text
前端
 ↓
网关
 ↓
订单服务
 ↓ OpenFeign
用户服务
```

这样用户登录 Token 可以继续传递。

---

# 14. 配置超时时间

OpenFeign 调用属于网络请求，因此一定要合理配置超时时间。

例如：

```yaml
spring:
  cloud:
    openfeign:
      client:
        config:
          default:
            connectTimeout: 3000
            readTimeout: 5000
```

含义：

```text
connectTimeout
```

连接服务的超时时间。

```text
readTimeout
```

连接成功后等待接口响应的时间。

例如：

```text
连接超时：3 秒
读取超时：5 秒
```

---

# 15. 单独配置某个服务

例如：

```yaml
spring:
  cloud:
    openfeign:
      client:
        config:

          default:
            connectTimeout: 3000
            readTimeout: 5000

          user-service:
            connectTimeout: 2000
            readTimeout: 3000
```

此时：

```text
user-service
```

使用独立配置。

其他服务使用：

```text
default
```

配置。

---

# 16. Feign 日志

开发和排查接口调用问题时，可以开启 Feign 日志。

配置日志级别：

```java
@Configuration
public class FeignConfig {

    @Bean
    Logger.Level feignLoggerLevel() {
        return Logger.Level.FULL;
    }
}
```

日志级别：

```text
NONE
BASIC
HEADERS
FULL
```

说明：

| 日志级别 | 内容 |
|---|---|
| NONE | 不打印 |
| BASIC | 方法、URL、状态码、耗时 |
| HEADERS | BASIC + 请求头 |
| FULL | 请求头、请求体、响应头、响应体 |

开发环境通常可以使用：

```java
Logger.Level.FULL
```

生产环境建议谨慎使用，避免日志过大或者泄露敏感数据。

同时配置：

```yaml
logging:
  level:
    com.example.feign: DEBUG
```

否则可能看不到 Feign 日志。

---

# 17. 使用 DTO

推荐 Feign 接口不要直接暴露数据库实体 Entity。

例如不要：

```java
@GetMapping("/user/{id}")
UserEntity getUser();
```

推荐：

```java
@GetMapping("/user/{id}")
UserDTO getUser();
```

服务之间使用：

```text
DTO
```

而不是：

```text
Entity
```

这样可以避免数据库模型变化直接影响服务调用。

---

# 18. 统一返回结构

如果系统接口返回：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "张三"
  }
}
```

可以定义：

```java
public class Result<T> {

    private Integer code;

    private String message;

    private T data;

}
```

Feign：

```java
@GetMapping("/user/{id}")
Result<UserDTO> getUser(
    @PathVariable("id") Long id
);
```

调用：

```java
Result<UserDTO> result =
    userFeignClient.getUser(1L);

UserDTO user = result.getData();
```

---

# 19. 服务注册中心调用

例如使用 Nacos。

Nacos 中存在：

```text
user-service
order-service
```

订单服务中：

```java
@FeignClient(name = "user-service")
public interface UserFeignClient {

    @GetMapping("/user/{id}")
    UserDTO getUser(
        @PathVariable("id") Long id
    );
}
```

OpenFeign 会通过服务发现找到：

```text
user-service
```

实例。

假设实例有：

```text
192.168.1.10:8081
192.168.1.11:8081
192.168.1.12:8081
```

OpenFeign 会结合 Spring Cloud LoadBalancer 选择一个服务实例。

大致流程：

```text
Order Service
      |
      | OpenFeign
      ↓
Service Discovery
      |
      ↓
user-service
      |
      ↓
LoadBalancer
      |
      ├── 192.168.1.10:8081
      ├── 192.168.1.11:8081
      └── 192.168.1.12:8081
```

---

# 20. OpenFeign 常见项目结构

推荐：

```text
src
└── main
    └── java
        └── com.example
            │
            ├── controller
            │
            ├── service
            │
            ├── dto
            │
            ├── feign
            │   ├── UserFeignClient.java
            │   └── OrderFeignClient.java
            │
            ├── config
            │   └── FeignConfig.java
            │
            └── Application.java
```

把所有远程接口统一放在：

```text
feign
```

或者：

```text
client
```

目录下。

例如：

```text
client/user/UserClient.java
client/order/OrderClient.java
client/trade/TradeClient.java
```

大型项目这样更容易维护。

---

# 21. FeignClient 命名建议

推荐使用：

```text
XxxClient
```

或者：

```text
XxxFeignClient
```

例如：

```java
UserClient
OrderClient
TradeClient
CustomerClient
```

或者：

```java
UserFeignClient
OrderFeignClient
```

项目内部保持统一即可。

---

# 22. 接口定义与 FeignClient

假设用户服务：

```java
@RestController
@RequestMapping("/api/user")
public class UserController {

    @GetMapping("/{id}")
    public UserDTO getUser(
        @PathVariable Long id
    ) {
        return userService.getUser(id);
    }
}
```

调用方：

```java
@FeignClient(
    name = "user-service",
    path = "/api/user"
)
public interface UserFeignClient {

    @GetMapping("/{id}")
    UserDTO getUser(
        @PathVariable("id") Long id
    );
}
```

调用：

```java
@Service
public class OrderService {

    private final UserFeignClient userFeignClient;

    public OrderService(
        UserFeignClient userFeignClient
    ) {
        this.userFeignClient = userFeignClient;
    }

    public void createOrder(Long userId) {

        UserDTO user =
            userFeignClient.getUser(userId);

        // 创建订单
    }
}
```

---

# 23. 常见错误

## 错误一：忘记开启 EnableFeignClients

表现：

```text
No qualifying bean of type UserFeignClient
```

解决：

```java
@EnableFeignClients
```

---

## 错误二：PathVariable 没有写 name

建议写：

```java
@PathVariable("id")
```

而不是：

```java
@PathVariable
```

例如：

```java
@GetMapping("/user/{id}")
UserDTO getUser(
    @PathVariable("id") Long id
);
```

兼容性会更好。

---

## 错误三：RequestParam 没写名称

推荐：

```java
@RequestParam("page")
```

例如：

```java
@GetMapping("/list")
List<UserDTO> list(
    @RequestParam("page") Integer page
);
```

---

## 错误四：服务名称不一致

例如注册中心实际服务：

```text
user-service
```

但代码：

```java
@FeignClient(name = "users-service")
```

会导致找不到服务实例。

---

## 错误五：Feign 超时

报错可能出现：

```text
Read timed out
```

或者：

```text
Connect timed out
```

需要检查：

```text
网络
服务状态
接口响应速度
Feign 超时时间
```

---

## 错误六：401 / 403

一般检查：

```text
Authorization 是否传递
Token 是否正确
网关鉴权
服务内部鉴权
```

特别是：

```text
A 服务
 ↓ Feign
B 服务
```

如果 B 服务需要 Token，需要确保 Token 被继续传递。

---

# 24. OpenFeign 与 RestTemplate 对比

RestTemplate：

```java
restTemplate.getForObject(
    "http://user-service/user/1",
    UserDTO.class
);
```

OpenFeign：

```java
userClient.getUser(1L);
```

OpenFeign 的优势：

```text
代码更少
接口定义清晰
更容易维护
天然适合微服务
可结合服务发现
可结合负载均衡
支持拦截器
支持统一配置
```

---

# 25. OpenFeign 调用流程

完整流程可以理解为：

```text
Controller
    ↓
Service
    ↓
FeignClient
    ↓
OpenFeign
    ↓
LoadBalancer
    ↓
服务注册中心
    ↓
目标服务实例
    ↓
HTTP 请求
    ↓
Controller
    ↓
返回 JSON
    ↓
Feign Decoder
    ↓
Java DTO
```

开发人员看到的代码可能只有：

```java
userClient.getUser(1L);
```

底层实际上完成了一次完整 HTTP 请求。

---

# 26. 推荐使用方式

项目中建议遵循以下原则：

1. FeignClient 只负责远程接口定义。
2. 不要在 FeignClient 中写业务逻辑。
3. 请求参数尽量使用 DTO。
4. 返回值尽量使用 DTO。
5. 不直接暴露 Entity。
6. 设置合理的连接和读取超时。
7. Token、TraceId 等公共 Header 使用拦截器统一处理。
8. Feign 调用异常需要统一捕获和处理。
9. 避免服务之间循环调用。
10. 高频接口调用需要考虑性能、超时和服务稳定性。

---

# 27. 一个完整示例

## FeignClient

```java
@FeignClient(
    name = "user-service",
    path = "/api/user",
    configuration = FeignConfig.class
)
public interface UserFeignClient {

    @GetMapping("/{id}")
    Result<UserDTO> getUser(
        @PathVariable("id") Long id
    );

    @GetMapping("/list")
    Result<List<UserDTO>> list(
        @RequestParam("page") Integer page,
        @RequestParam("size") Integer size
    );

    @PostMapping
    Result<UserDTO> create(
        @RequestBody CreateUserDTO dto
    );
}
```

## Service

```java
@Service
public class OrderService {

    private final UserFeignClient userFeignClient;

    public OrderService(
        UserFeignClient userFeignClient
    ) {
        this.userFeignClient = userFeignClient;
    }

    public void createOrder(Long userId) {

        Result<UserDTO> result =
            userFeignClient.getUser(userId);

        UserDTO user = result.getData();

        System.out.println(user.getName());
    }
}
```

---

# 28. 一句话理解 OpenFeign

OpenFeign 本质上就是：

```text
Java 接口
    ↓
自动转换为 HTTP 请求
    ↓
调用其他服务 REST API
```

原本需要手动写：

```text
URL
HTTP 方法
参数
Header
JSON 转换
        响应解析
```

OpenFeign 把这些操作封装起来，让微服务调用看起来更像普通 Java 方法调用：

```java
userClient.getUser(userId);
```

因此在 Spring Cloud 微服务项目中，OpenFeign 通常作为服务之间 HTTP 调用的主要方案之一。


# Sentinel

![image.png](/static/img/34d3ac10bd657c676153f386db7c5bfa.image.webp)

![image.png](/static/img/b13370713deebcd33e138c8adf5365ea.image.webp)

![image.png](/static/img/e01ad09e551c3464a0bbedc4918111fc.image.webp)

![image.png](/static/img/b5be7428e43382af4aa00f130e0ed89f.image.webp)

![image.png](/static/img/48499c78de7e18af90f9e394aca32cd1.image.webp)

![image.png](/static/img/7b8997fa2061ec059b4e0d3b53a12cb4.image.webp)

SpringClould

## 1.快捷键

![image.png](/static/img/6a58627bf71e4fbc109f3dfae248bb66.image.webp)



## 2.建模过程
建模 => 布光 => 材质 => 渲染

blender学习

## DSH-better-sidebar：
直接把侧边栏变成开发工作台，集成文件查看/编辑、终端、Git、子 Agent 等，用起来更接近 Cursor / IDE Agent。



## dsh-git-status：
Git 体验增强，有提交 DAG、未提交修改、stash、inline diff、分支操作。AI 改了一堆代码之后检查改动特别方便。
## dsh-lsp-actions：
很适合真正拿 DSH 写工程代码。给 Agent 提供 LSP 的诊断、格式化、补全、Code Action、符号、签名、Rename 等能力，比单纯“搜索字符串然后改代码”靠谱很多。
## dsh-plans：
复杂需求非常推荐。先研究项目 → 生成 Markdown 计划 → reviewer/critic 子 Agent 检查 → 再执行，很适合“给现有 Vue 项目新增一个完整模块”这种任务。
## dsh-web-search-pro：
联网搜索加强版，支持多搜索引擎、GitHub/B站/YouTube/知乎/微博等平台、SQLite 缓存以及 Playwright 网页渲染。查 npm/Vue/Spring 文档、GitHub Issue 会比较爽。它目前提供 9 个搜索相关工具。
## dsh-toolkit：
属于“基础设施插件”，有 calculator、JSON、CSV、regex、Markdown、diff、统计、schema 等确定性工具，不是什么花活，但日常 Agent 很容易用到。
## dsh-auto-continue：
很实用的小插件。网络异常、超时等导致任务中断时，可以自动发送“继续”恢复任务，适合长时间重构、跑测试这种流程。
## dsh-permission-rules：
如果你开始让 Agent 自主跑 shell、改文件，建议装。类似 Claude Code 的 allow / deny / ask 权限规则，可以针对工具、参数和工作区路径限制操作。


```js
DSH-better-sidebar
dsh-git-status
dsh-lsp-actions
dsh-plans
dsh-web-search-pro
dsh-auto-continue
```