Resmic's | BLOG

PHP 8.3 新特性实战：从 Readonly 类到 Fibers 协程的完整升级指南

Mon, 06 Apr 2026 08:13:17 +0800

为什么要迁移到 PHP 8.3？

PHP 8.3 于 2023 年 11 月正式发布，距今已成为生产环境中的主流版本。相比 PHP 7.x，整个 PHP 8.x 系列带来了质的飞跃：JIT 编译器、枚举类型、Fibers 协程、readonly 属性等一系列重磅特性，让 PHP 的开发体验和运行性能都上了一个台阶。

如果你的项目还运行在 PHP 7.4 或 PHP 8.0/8.1，这篇文章将带你系统了解 PHP 8.3 的核心新特性，并通过实际代码演示如何在项目中落地应用，让你看完就能动手升级。

PHP 7.4 已于 2022 年 11 月停止安全支持
PHP 8.0 已于 2023 年 11 月停止安全支持
PHP 8.3 支持到 2026 年 12 月，是当前最推荐的版本

特性一：Readonly 类（Readonly Classes）

PHP 8.1 引入了 readonly 属性，8.2 将其升级为 Readonly 类。在 PHP 8.2+ 中，你可以直接用 readonly 修饰整个类，使所有属性自动成为只读的，非常适合用于值对象（Value Object）和 DTO 场景。

<?php

// PHP 8.1 的方式：每个属性都要加 readonly
class UserDTO_Old {
    public function __construct(
        public readonly int $id,
        public readonly string $name,
        public readonly string $email,
    ) {}
}

// PHP 8.2+ 的方式：直接修饰类
readonly class UserDTO {
    public function __construct(
        public int $id,
        public string $name,
        public string $email,
    ) {}
}

$user = new UserDTO(id: 1, name: '张三', email: 'zhangsan@example.com');
echo $user->name; // 张三

// 尝试修改会抛出错误
$user->name = '李四'; // Error: Cannot modify readonly property

⚠️ 踩坑记录： readonly 类不支持非类型化属性，所有属性都必须有类型声明。另外，readonly 类不能被继承为非 readonly 类，如果你的 DTO 需要继承扩展，要提前规划好类层级结构。

特性二：枚举类型（Enums）的最佳实践

PHP 8.1 引入了原生枚举，解决了长期以来用类常量模拟枚举的痛点。PHP 8.3 对枚举做了进一步优化，下面来看几个实战场景。

<?php

// 纯枚举（Pure Enum）
enum Status {
    case Active;
    case Inactive;
    case Pending;
}

// 支持值的枚举（Backed Enum）- 推荐用于数据库存储
enum OrderStatus: string {
    case Created  = 'created';
    case Paid     = 'paid';
    case Shipped  = 'shipped';
    case Done     = 'done';
    case Canceled = 'canceled';

    // 枚举可以有方法
    public function label(): string {
        return match($this) {
            self::Created  => '待支付',
            self::Paid     => '已支付',
            self::Shipped  => '已发货',
            self::Done     => '已完成',
            self::Canceled => '已取消',
        };
    }

    // 枚举可以实现接口
    public function isTerminal(): bool {
        return in_array($this, [self::Done, self::Canceled]);
    }
}

// 使用示例
$status = OrderStatus::Paid;
echo $status->value;      // paid
echo $status->label();    // 已支付
echo $status->isTerminal() ? '终态' : '非终态'; // 非终态

// 从数据库值转换
$fromDb = OrderStatus::from('shipped');         // 严格转换，找不到抛异常
$fromDb2 = OrderStatus::tryFrom('unknown');     // 安全转换，找不到返回 null

// 枚举用于类型约束
function updateOrderStatus(int $orderId, OrderStatus $newStatus): void {
    // 编译时就能检查类型，再也不怕传入不合法的状态值
    // ...
}

在 Laravel/Symfony 等框架中，枚举可以直接用于路由参数类型绑定和 Eloquent 属性转换（cast），极大简化了状态机的实现。

特性三：Fibers 协程实战（PHP 8.1+）

Fibers 是 PHP 8.1 引入的轻量级并发原语，可以理解为"可中断的函数"。它不是多线程，而是在单线程内实现协作式调度，是构建异步框架（如 ReactPHP、Amp v3）的底层基础。

<?php

// 基础示例：理解 Fiber 的暂停和恢复
$fiber = new Fiber(function(): string {
    echo "Fiber 开始执行\n";
    
    $valueFromMain = Fiber::suspend('第一次暂停，传给主程序的值');
    echo "Fiber 恢复，主程序传来：{$valueFromMain}\n";
    
    Fiber::suspend('第二次暂停');
    echo "Fiber 再次恢复\n";
    
    return '最终返回值';
});

// 启动 Fiber
$val1 = $fiber->start();          // 输出 "Fiber 开始执行"，返回 "第一次暂停，传给主程序的值"
echo "主程序收到：{$val1}\n";

$val2 = $fiber->resume('hello'); // Fiber 恢复执行，传入 "hello"
echo "主程序收到：{$val2}\n";

$fiber->resume();                  // 最终恢复
echo "Fiber 返回：" . $fiber->getReturn() . "\n";

实战场景——用 Fiber 实现简单的并发 HTTP 请求（配合 curl_multi）：

<?php

function fetchAsync(array $urls): array {
    $multiHandle = curl_multi_init();
    $fibers = [];
    $results = [];

    foreach ($urls as $key => $url) {
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 10);
        curl_multi_add_handle($multiHandle, $ch);

        // 每个 URL 对应一个 Fiber
        $fibers[$key] = [
            'fiber' => new Fiber(function() use ($ch, $multiHandle) {
                // 等待请求完成
                while (curl_multi_exec($multiHandle, $active) && $active) {
                    Fiber::suspend(); // 让出控制权
                }
                return curl_multi_getcontent($ch);
            }),
            'ch' => $ch,
        ];
    }

    // 启动所有 Fiber
    foreach ($fibers as $key => $item) {
        $item['fiber']->start();
    }

    // 调度循环
    do {
        $running = false;
        foreach ($fibers as $key => $item) {
            if (!$item['fiber']->isTerminated()) {
                $item['fiber']->resume();
                $running = true;
            } else {
                $results[$key] = $item['fiber']->getReturn();
            }
        }
    } while ($running);

    curl_multi_close($multiHandle);
    return $results;
}

$responses = fetchAsync([
    'baidu' => 'https://www.baidu.com',
    'github' => 'https://api.github.com',
]);

⚠️ 踩坑记录： Fiber 不是真正的并行，不能跨 Fiber 共享状态，不要在 Fiber 内捕获外部引用后修改，否则容易出现竞态问题。推荐使用 Amp v3 或 ReactPHP 这类成熟框架，它们已经帮你处理好了事件循环和调度逻辑。

特性四：PHP 8.3 新增 — 类常量类型声明

PHP 8.3 终于支持了类常量的类型声明！这解决了长期以来常量类型不明确的问题，让 IDE 的静态分析和代码补全更加精准。

<?php

class Config {
    // PHP 8.3 新特性：类常量可以声明类型了
    const string APP_NAME    = 'MyApp';
    const string APP_VERSION = '1.0.0';
    const int    MAX_RETRIES = 3;
    const float  TAX_RATE    = 0.08;
    const array  ALLOWED_IPS = ['127.0.0.1', '::1'];

    // 接口中同样支持
}

interface Configurable {
    const string DEFAULT_LOCALE = 'zh_CN';
}

// 类型不匹配会直接报错
class BadConfig {
    const int WRONG_TYPE = 'not_an_int'; // Fatal error: Cannot use string as int constant value
}

特性五：PHP 8.3 新增 — json_validate() 函数

以前验证 JSON 字符串是否合法，需要先 json_decode 再检查 json_last_error()，既低效又啰嗦。PHP 8.3 直接内置了 json_validate() 函数。

<?php

// 旧方式（PHP 8.2 及以前）
function isValidJson_Old(string $json): bool {
    json_decode($json);
    return json_last_error() === JSON_ERROR_NONE;
}

// PHP 8.3 新方式 - 不解码，只验证，更高效
$validJson   = '{"name": "张三", "age": 30}';
$invalidJson = '{name: "张三"}'; // 键名没加引号

var_dump(json_validate($validJson));   // bool(true)
var_dump(json_validate($invalidJson)); // bool(false)

// 支持深度限制参数
var_dump(json_validate('{"a":{"b":{"c":1}}}', depth: 2)); // bool(false) 超过深度限制
var_dump(json_validate('{"a":{"b":{"c":1}}}', depth: 5)); // bool(true)

// 实际应用：API 请求体校验
function handleWebhook(string $rawBody): array {
    if (!json_validate($rawBody)) {
        throw new \InvalidArgumentException('Invalid JSON payload');
    }
    return json_decode($rawBody, associative: true);
}

实战：从 PHP 8.0 升级到 PHP 8.3 的完整步骤

了解了新特性后，我们来看如何安全地进行版本迁移。以下是一个经过实战验证的升级流程：

第一步：检测兼容性

# 安装 PHP Compatibility 检查工具
composer require --dev phpcompatibility/php-compatibility

# 配置 phpcs.xml
vendor/bin/phpcs --config-set installed_paths vendor/phpcompatibility/php-compatibility

# 扫描整个项目，检测 PHP 8.3 不兼容的写法
vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.3 src/

第二步：常见破坏性变更处理

动态属性废弃（PHP 8.2）： 未在类中声明的属性赋值会触发废弃警告，PHP 9 将报错。需要将动态属性显式声明，或加 #[AllowDynamicProperties] 属性注解。
字符串与数字比较（PHP 8.0）： 0 == "foo" 从 true 变成 false，检查所有类型转换逻辑。
match 表达式无默认： PHP 8 的 match 不匹配时抛 UnhandledMatchError，注意加默认分支。

<?php

// PHP 8.0 之前（会触发警告）
class OldModel {
    public function setData(array $data): void {
        foreach ($data as $key => $val) {
            $this->$key = $val; // 动态赋值，PHP 8.2 警告，PHP 9 报错
        }
    }
}

// PHP 8.2+ 修复方式
#[\AllowDynamicProperties]
class NewModel {
    // 或者改用数组存储动态数据
    private array $attributes = [];
    
    public function setAttribute(string $key, mixed $value): void {
        $this->attributes[$key] = $value;
    }
    
    public function __get(string $name): mixed {
        return $this->attributes[$name] ?? null;
    }
}

第三步：Laravel/Symfony 框架升级注意

Laravel 10.x 和 11.x 已完全支持 PHP 8.3，直接升级 PHP 版本即可
Symfony 6.4 和 7.x 支持 PHP 8.3，检查各 Bundle 的兼容性
运行完整测试套件，重点关注类型相关的 deprecation 警告
Docker 镜像从 php:8.0-fpm 更换为 php:8.3-fpm-alpine

第四步：性能测试对比

# 用 ab 做简单压测对比（升级前后各跑一次）
ab -n 1000 -c 10 https://yoursite.com/api/heavy-endpoint

# 或用 wrk（更精准）
wrk -t4 -c100 -d30s https://yoursite.com/api/heavy-endpoint

根据实测，同等配置下 PHP 8.3 比 PHP 7.4 平均性能提升 30-50%，比 PHP 8.0 也有 5-15% 的提升，JIT 对计算密集型任务效果最为显著。

总结

PHP 8.3 带来的改进是全方位的：从 Readonly 类到枚举类型，从 Fibers 协程到类常量类型声明，再到 json_validate() 这样细心的 API 填补，都体现了 PHP 语言在工程化和现代化道路上的持续进步。

升级建议：

新项目直接用 PHP 8.3，充分利用所有新特性
老项目先用 PHPCompatibility 扫描，逐步修复，配合完善的测试再切换
重点利用 readonly 类和枚举重构数据对象，代码会简洁很多
生产环境建议先在预发环境验证至少一周再全量切换

现在就开始你的 PHP 8.3 升级之旅吧，让代码更安全、更优雅、更高效！

MCP 工具开发实战：从零给 AI 接入任意 API 的完整指南

Sun, 05 Apr 2026 08:07:27 +0800

MCP（Model Context Protocol）是 Anthropic 在 2024 年底发布的开放协议，旨在让 AI 助手能够安全、标准化地接入任意外部 API 和数据源。简单理解：它就像给 AI 装上了"插件系统"——你写一个 MCP Server，AI 就能调用你提供的工具，无论是查数据库、调用内部 API，还是操控本地文件系统，都能一把搞定。

本文以一个真实场景为例：为 AI 助手开发一个能查询公司内部项目状态的 MCP Server，从零开始，覆盖协议原理、开发环境搭建、工具定义、鉴权处理、调试技巧到实际接入 Claude Desktop，让你看完就能动手。

一、MCP 是什么？为什么你需要它

在 MCP 出现之前，想让 AI 接入外部系统，每个平台都要单独实现"Function Calling"或"Tool Use"——OpenAI 有一套格式，Claude 有一套格式，各家 Agent 框架又各有不同。开发者苦不堪言，要么为每个平台单独维护集成代码，要么依赖某个框架的封装（但框架升级就可能崩）。

MCP 的目标是统一这个混乱局面。它定义了一套标准的 Client-Server 通信协议：

MCP Server：你开发的工具提供方，暴露一组可调用的"工具"（Tools）、可读取的"资源"（Resources）和可使用的"提示词"（Prompts）
MCP Client：集成在 AI 助手中的协议客户端，负责发现、调用 MCP Server 提供的能力
传输层：支持 stdio（本地进程通信）和 HTTP+SSE（远程服务）两种方式

目前支持 MCP 的平台已经相当丰富：Claude Desktop、Cursor、Continue、Cline、以及各种基于 LangChain/LlamaIndex 构建的 Agent 框架。一次开发，处处可用。

回到我们的场景：公司有一套内部项目管理系统，提供 REST API，但 Claude Desktop 没法直接查它。通过 MCP，我们可以让 AI 直接回答"目前有哪些进行中的项目"、"张三负责哪些任务"这类问题，而不需要用户手动去系统里查再粘贴给 AI。

二、开发环境搭建

MCP SDK 目前官方支持 Python 和 TypeScript，本文使用 Python（更适合快速原型）。

# 推荐用 uv 管理 Python 环境（比 pip + venv 更快更干净）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建项目
mkdir mcp-project-server && cd mcp-project-server
uv init --python 3.11
uv add mcp httpx python-dotenv

# 目录结构
.
├── .env                 # 存放 API Token（不提交到 git）
├── pyproject.toml
└── src/
    └── server.py        # MCP Server 主文件

关于 Python 版本：MCP SDK 要求 Python 3.10+，推荐 3.11 或 3.12，3.13 目前个别依赖还有兼容问题。

创建 .env 文件，存放内部系统的 API 配置：

PROJECT_API_BASE=https://internal.company.com/api/v2
PROJECT_API_TOKEN=your_secret_token_here

三、核心代码：定义你的第一个 MCP 工具

MCP Server 的核心是定义"工具"——每个工具对应一个 AI 可以调用的操作，类似 OpenAI 的 Function Calling，但格式更标准化。

# src/server.py
import asyncio
import os
from dotenv import load_dotenv
import httpx
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types

load_dotenv()

API_BASE = os.getenv("PROJECT_API_BASE")
API_TOKEN = os.getenv("PROJECT_API_TOKEN")

app = Server("project-server")

# 定义工具列表（AI 会根据这些描述决定什么时候调用哪个工具）
@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="list_projects",
            description="列出公司内部项目列表，可按状态筛选（进行中/已完成/暂停）",
            inputSchema={
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": ["active", "completed", "paused", "all"],
                        "description": "项目状态筛选，默认为 all",
                        "default": "all"
                    },
                    "limit": {
                        "type": "integer",
                        "description": "返回数量上限，默认 20",
                        "default": 20
                    }
                }
            }
        ),
        types.Tool(
            name="get_project_detail",
            description="获取指定项目的详细信息，包括任务列表、负责人、进度等",
            inputSchema={
                "type": "object",
                "properties": {
                    "project_id": {
                        "type": "string",
                        "description": "项目 ID"
                    }
                },
                "required": ["project_id"]
            }
        ),
        types.Tool(
            name="search_tasks_by_assignee",
            description="查询某个员工负责的所有任务",
            inputSchema={
                "type": "object",
                "properties": {
                    "assignee": {
                        "type": "string",
                        "description": "员工姓名或工号"
                    },
                    "status": {
                        "type": "string",
                        "enum": ["todo", "in_progress", "done", "all"],
                        "default": "all"
                    }
                },
                "required": ["assignee"]
            }
        )
    ]

工具描述（description）非常关键——AI 就是根据这段文字来判断什么时候应该调用这个工具的。描述要清晰、具体，说清楚这个工具能做什么、适合什么场景。模糊的描述会导致 AI 乱调或不调。

四、实现工具逻辑：对接真实 API

工具定义好之后，需要实现实际的调用逻辑。当 AI 决定使用某个工具时，MCP 框架会触发 call_tool 处理器：

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    headers = {
        "Authorization": f"Bearer {API_TOKEN}",
        "Content-Type": "application/json"
    }
    
    async with httpx.AsyncClient(timeout=10.0) as client:
        try:
            if name == "list_projects":
                status = arguments.get("status", "all")
                limit = arguments.get("limit", 20)
                
                params = {"limit": limit}
                if status != "all":
                    params["status"] = status
                
                resp = await client.get(
                    f"{API_BASE}/projects",
                    headers=headers,
                    params=params
                )
                resp.raise_for_status()
                data = resp.json()
                
                # 格式化输出——让 AI 更容易理解
                projects = data.get("items", [])
                if not projects:
                    return [types.TextContent(type="text", text="没有找到符合条件的项目")]
                
                lines = [f"共找到 {len(projects)} 个项目：\n"]
                for p in projects:
                    lines.append(
                        f"- [{p['id']}] {p['name']} | 状态: {p['status']} | "
                        f"负责人: {p.get('owner', '未分配')} | "
                        f"截止日期: {p.get('due_date', '未设置')}"
                    )
                return [types.TextContent(type="text", text="\n".join(lines))]
            
            elif name == "get_project_detail":
                project_id = arguments["project_id"]
                resp = await client.get(
                    f"{API_BASE}/projects/{project_id}",
                    headers=headers
                )
                resp.raise_for_status()
                p = resp.json()
                
                tasks = p.get("tasks", [])
                task_summary = "\n".join([
                    f"  - {t['title']} [{t['status']}] 负责人: {t.get('assignee', '未分配')}"
                    for t in tasks[:10]  # 最多显示10条
                ])
                
                result = f"""项目详情：{p['name']} (ID: {p['id']})
状态: {p['status']}
描述: {p.get('description', '无')}
开始日期: {p.get('start_date', '未设置')}
截止日期: {p.get('due_date', '未设置')}
项目负责人: {p.get('owner', '未分配')}
完成进度: {p.get('progress', 0)}%

任务列表 (共{len(tasks)}条，显示前10条):
{task_summary}"""
                
                return [types.TextContent(type="text", text=result)]
            
            elif name == "search_tasks_by_assignee":
                assignee = arguments["assignee"]
                status = arguments.get("status", "all")
                
                params = {"assignee": assignee}
                if status != "all":
                    params["status"] = status
                
                resp = await client.get(
                    f"{API_BASE}/tasks/search",
                    headers=headers,
                    params=params
                )
                resp.raise_for_status()
                data = resp.json()
                
                tasks = data.get("items", [])
                if not tasks:
                    return [types.TextContent(type="text", text=f"未找到 {assignee} 的任务")]
                
                lines = [f"{assignee} 共有 {len(tasks)} 个任务：\n"]
                for t in tasks:
                    lines.append(
                        f"- [{t['project_name']}] {t['title']} | "
                        f"状态: {t['status']} | 截止: {t.get('due_date', '未设置')}"
                    )
                return [types.TextContent(type="text", text="\n".join(lines))]
            
            else:
                return [types.TextContent(type="text", text=f"未知工具: {name}")]
        
        except httpx.HTTPStatusError as e:
            return [types.TextContent(
                type="text",
                text=f"API 调用失败: HTTP {e.response.status_code} - {e.response.text[:200]}"
            )]
        except httpx.TimeoutException:
            return [types.TextContent(type="text", text="请求超时，内部系统可能暂时不可用")]
        except Exception as e:
            return [types.TextContent(type="text", text=f"意外错误: {str(e)}")]


# 启动 Server
if __name__ == "__main__":
    asyncio.run(stdio_server(app))

有几个踩坑点值得注意：

超时必须设置：内部 API 有时会卡住，不设超时会导致 MCP 连接假死
错误信息要对 AI 友好：不要直接抛异常，返回清晰的文字说明，让 AI 能告知用户具体出了什么问题
输出格式要清晰：AI 会把工具返回的文本直接作为上下文，格式越清晰，AI 理解越准确，回答越好

五、本地调试：不依赖任何 AI 客户端

开发过程中频繁切换到 Claude Desktop 测试非常低效。MCP SDK 提供了命令行调试工具，可以直接在终端验证工具是否正常工作：

# 方法一：使用 mcp dev 工具（推荐）
uv run mcp dev src/server.py

# 这会启动一个交互式 Inspector，在浏览器中打开 http://localhost:5173
# 可以直接列出工具、手动填参数调用、查看返回结果

如果没有图形界面，也可以用脚本直接测试：

# 方法二：写测试脚本
# test_server.py
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test():
    server_params = StdioServerParameters(
        command="uv",
        args=["run", "src/server.py"],
        env=None
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # 初始化
            await session.initialize()
            
            # 列出所有工具
            tools = await session.list_tools()
            print("可用工具：")
            for t in tools.tools:
                print(f"  - {t.name}: {t.description}")
            
            # 调用工具测试
            result = await session.call_tool(
                "list_projects",
                arguments={"status": "active", "limit": 5}
            )
            print("\n调用结果：")
            for content in result.content:
                print(content.text)

asyncio.run(test())

调试阶段的常见问题：

Server 启动失败：99% 是 .env 没有正确加载，加一行 print(os.getenv("PROJECT_API_BASE")) 确认
工具列表为空：检查 @app.list_tools() 装饰器是否正确，函数签名是否匹配
工具调用报错但无堆栈：MCP 会吞掉未捕获的异常，记得在 call_tool 里加宽泛的 try/except 并打印

六、接入 Claude Desktop：最后一步

代码调通之后，接入 Claude Desktop 只需修改一个配置文件。找到 Claude Desktop 的配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "project-server": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/mcp-project-server",
        "python",
        "src/server.py"
      ],
      "env": {
        "PROJECT_API_BASE": "https://internal.company.com/api/v2",
        "PROJECT_API_TOKEN": "your_secret_token_here"
      }
    }
  }
}

保存后完全退出并重启 Claude Desktop（注意是完全退出，不是最小化）。重启后在对话框左下角会出现工具图标，点击可以看到你注册的工具列表。

现在你可以直接问 Claude："帮我看看目前有哪些进行中的项目，以及张三负责什么任务？"它会自动决定调用哪些工具，汇总结果给你。

几个配置的注意事项：

用 uv run 而不是 python：确保使用项目虚拟环境中的依赖，避免包版本冲突
env 中的变量会覆盖系统环境变量：不同项目可以有不同的 Token，互不干扰
路径用绝对路径：相对路径在 Claude Desktop 启动时可能解析错误

七、进阶：添加 Resources 和 Prompts

除了 Tools，MCP 还支持 Resources（让 AI 读取数据，如文档、日志）和 Prompts（预定义的提示词模板）。在我们的项目中，可以加一个 Resource，让 AI 直接读取项目的 README：

from mcp import types
from mcp.server import Server

@app.list_resources()
async def list_resources() -> list[types.Resource]:
    return [
        types.Resource(
            uri="project://docs/workflow",
            name="项目工作流规范",
            description="公司内部项目管理流程和规范文档",
            mimeType="text/markdown"
        )
    ]

@app.read_resource()
async def read_resource(uri: str) -> str:
    if uri == "project://docs/workflow":
        # 从内部 API 或文件读取
        async with httpx.AsyncClient() as client:
            resp = await client.get(
                f"{API_BASE}/docs/workflow",
                headers={"Authorization": f"Bearer {API_TOKEN}"}
            )
            return resp.text
    raise ValueError(f"未知资源: {uri}")

Resources 和 Tools 的区别：Resources 是 AI "主动读取"的数据，Tools 是 AI "主动调用"的操作。前者适合静态或半静态的内容（文档、配置），后者适合需要参数的动态查询。

八、踩坑总结与最佳实践

经过实际项目开发，总结了以下关键经验：

工具数量不要太多：超过 10-15 个工具，AI 的工具选择准确率会下降。相关功能尽量合并，用参数区分
描述比代码更重要：Tool 的 description 写得好，AI 调用准确率能提升 30%+。花时间打磨描述
返回结构化文本而非 JSON：虽然 JSON 看起来更"专业"，但 AI 处理自然语言描述更高效，报错也更清晰
做好降级处理：API 不可用时，返回友好提示而非让 MCP 崩溃，用户体验差很多
注意敏感信息：Token、密码不要打印到 stdout（MCP stdio 模式下 stdout 就是通信通道），用 stderr 打印日志
版本锁定：mcp SDK 还在快速迭代，pyproject.toml 中锁定精确版本避免升级破坏

MCP 生态目前还在高速成长，官方 Server 仓库（github.com/modelcontextprotocol/servers）已经有几十个现成实现可以参考，包括 GitHub、Slack、数据库等常见场景。如果你的需求和现有实现相似，直接 fork 改改比从零写更快。

最后：MCP 的价值不仅是技术上的标准化，更是工作方式的改变——以后不用打开十几个系统查信息，直接问 AI 就好了。

PHP 8.x 新特性实战：Enum、只读类、Fibers 完整开发教程

Sat, 04 Apr 2026 08:07:19 +0800

为什么要升级到 PHP 8.x？

PHP 8.x 系列（8.1、8.2、8.3）带来了大量改变游戏规则的新特性，很多特性能直接减少代码量、提升类型安全、增强运行性能。然而不少团队仍在跑 PHP 7.4，原因是"没时间研究新特性"或"不知道升了有什么用"。

本文不讲理论，全程用真实项目场景演示以下核心特性：

Fibers（协程纤程）：实现轻量级并发，告别 ReactPHP 的复杂度
枚举（Enum）：替代常量类，消灭魔法字符串
只读属性与只读类：构建不可变值对象，防止意外修改
Intersection Types（交叉类型）：更精确的类型约束
命名参数（Named Arguments）：让函数调用自文档化
match 表达式：switch 的强类型升级版

每个特性都会给出：用途说明 → 旧写法对比 → 新写法实战 → 踩坑点提醒。

Fibers：PHP 的协程支持终于来了

PHP 8.1 引入了 Fibers，这是 PHP 原生协程的基础。它允许暂停和恢复一段函数执行，非常适合实现异步任务调度器、流式响应等场景。

理解 Fiber 的关键：它不是多线程，而是协作式多任务——你主动让出控制权，主程序继续执行其他任务，之后再恢复你。

基本用法示例：

<?php
// 创建一个 Fiber
$fiber = new Fiber(function(): void {
    echo "Fiber 开始执行\n";
    $value = Fiber::suspend('第一次挂起');  // 挂起，传值给外部
    echo "Fiber 恢复，收到: {$value}\n";
    Fiber::suspend('第二次挂起');
    echo "Fiber 结束\n";
});

// 启动 Fiber，直到第一次 suspend
$result1 = $fiber->start();
echo "外部收到: {$result1}\n";  // 输出: 外部收到: 第一次挂起

// 恢复 Fiber，传入一个值
$result2 = $fiber->resume('外部传入的数据');
echo "外部收到: {$result2}\n";  // 输出: 外部收到: 第二次挂起

$fiber->resume();  // 最后一次恢复，Fiber 结束

实战场景：简易任务调度器

<?php
class SimpleScheduler {
    private array $fibers = [];

    public function addTask(callable $callback): void {
        $this->fibers[] = new Fiber($callback);
    }

    public function run(): void {
        // 初始化所有 Fiber
        foreach ($this->fibers as $fiber) {
            $fiber->start();
        }

        // 循环调度，直到所有 Fiber 完成
        while (!empty($this->fibers)) {
            foreach ($this->fibers as $key => $fiber) {
                if ($fiber->isSuspended()) {
                    $fiber->resume();
                } elseif ($fiber->isTerminated()) {
                    unset($this->fibers[$key]);
                }
            }
        }
    }
}

$scheduler = new SimpleScheduler();

$scheduler->addTask(function() {
    echo "任务A: 第一步\n";
    Fiber::suspend();
    echo "任务A: 第二步\n";
    Fiber::suspend();
    echo "任务A: 完成\n";
});

$scheduler->addTask(function() {
    echo "任务B: 第一步\n";
    Fiber::suspend();
    echo "任务B: 完成\n";
});

$scheduler->run();
// 输出顺序：任务A第一步 → 任务B第一步 → 任务A第二步 → 任务B完成 → 任务A完成

⚠️ 踩坑：Fiber 不能跨 Fiber 调用 Fiber::suspend()，必须在当前 Fiber 内部调用。另外，Fiber 异常不会自动冒泡到外部，需要用 try/catch 在 Fiber 内部处理，或通过 $fiber->getReturn() 检查结果。

枚举（Enum）：消灭魔法字符串和常量类

PHP 8.1 之前，我们用常量类或 const 数组来表示有限状态集，代码重复且不类型安全。现在 Enum 原生支持了。

旧写法（常量类，PHP 7.x）：

<?php
class OrderStatus {
    const PENDING   = 'pending';
    const PAID      = 'paid';
    const SHIPPED   = 'shipped';
    const CANCELLED = 'cancelled';
}

// 调用时没有类型约束，传什么字符串都行，IDE 也不会报错
function processOrder(string $status): void {
    if ($status === OrderStatus::PAID) {
        // ...
    }
}

processOrder('piad');  // 拼写错误，运行时才发现

新写法（PHP 8.1+ Enum）：

<?php
enum OrderStatus: string {
    case Pending   = 'pending';
    case Paid      = 'paid';
    case Shipped   = 'shipped';
    case Cancelled = 'cancelled';

    // Enum 可以有方法！
    public function label(): string {
        return match($this) {
            OrderStatus::Pending   => '待支付',
            OrderStatus::Paid      => '已支付',
            OrderStatus::Shipped   => '已发货',
            OrderStatus::Cancelled => '已取消',
        };
    }

    public function canTransitionTo(OrderStatus $next): bool {
        return match($this) {
            OrderStatus::Pending   => $next === OrderStatus::Paid || $next === OrderStatus::Cancelled,
            OrderStatus::Paid      => $next === OrderStatus::Shipped,
            OrderStatus::Shipped   => false,
            OrderStatus::Cancelled => false,
        };
    }
}

// 使用
function processOrder(OrderStatus $status): void {
    echo "当前状态: " . $status->label() . "\n";
    
    if ($status->canTransitionTo(OrderStatus::Shipped)) {
        echo "可以发货\n";
    }
}

processOrder(OrderStatus::Paid);  // ✅
// processOrder('piad');  // ❌ 直接类型错误，IDE 实时提示

// 从数据库值恢复 Enum
$dbValue = 'paid';
$status = OrderStatus::from($dbValue);  // 找不到会抛异常
$status2 = OrderStatus::tryFrom('unknown');  // 找不到返回 null，更安全

Enum 实现接口（高级用法）：

<?php
interface HasColor {
    public function color(): string;
}

enum Suit: string implements HasColor {
    case Hearts   = 'H';
    case Diamonds = 'D';
    case Clubs    = 'C';
    case Spades   = 'S';

    public function color(): string {
        return match($this) {
            Suit::Hearts, Suit::Diamonds => 'red',
            Suit::Clubs, Suit::Spades   => 'black',
        };
    }
}

echo Suit::Hearts->color();  // 输出: red

⚠️ 踩坑：纯 Enum（不带类型声明）的 case 没有 value，不能用 ->value；带类型（enum X: string）才有。from() 和 tryFrom() 只对 backed enum 有效。Enum 不支持 new 实例化，也不支持 extends 继承其他类。

只读属性与只读类：构建不可变值对象

PHP 8.1 引入了只读属性（readonly），PHP 8.2 进一步引入了只读类（readonly class）。这对于领域驱动设计（DDD）中的值对象（Value Object）来说是天作之合。

场景：构建一个金额值对象

<?php
// PHP 8.2+ 只读类：所有属性自动变为 readonly
readonly class Money {
    public function __construct(
        public int    $amount,    // 金额（分），防止浮点数精度问题
        public string $currency,  // 货币代码，如 CNY
    ) {
        if ($amount < 0) {
            throw new \InvalidArgumentException("金额不能为负数: {$amount}");
        }
        if (strlen($currency) !== 3) {
            throw new \InvalidArgumentException("货币代码必须为3位: {$currency}");
        }
    }

    public function add(Money $other): self {
        if ($this->currency !== $other->currency) {
            throw new \DomainException("不同币种不能相加");
        }
        return new self($this->amount + $other->amount, $this->currency);
    }

    public function format(): string {
        return number_format($this->amount / 100, 2) . ' ' . $this->currency;
    }
    
    public function equals(Money $other): bool {
        return $this->amount === $other->amount 
            && $this->currency === $other->currency;
    }
}

$price = new Money(9900, 'CNY');   // 99.00 CNY
$tax   = new Money(891,  'CNY');   // 8.91 CNY
$total = $price->add($tax);

echo $total->format();  // 输出: 108.91 CNY

// $price->amount = 100;  // ❌ 报错：Cannot modify readonly property

PHP 8.1 单个属性只读（更细粒度控制）：

<?php
class User {
    public readonly string $id;
    public string $name;  // 可修改
    public readonly string $email;  // 注册后不可修改

    public function __construct(string $id, string $name, string $email) {
        $this->id    = $id;
        $this->name  = $name;
        $this->email = $email;
    }
    
    public function rename(string $newName): void {
        $this->name = $newName;  // ✅ 可以修改
        // $this->email = '...'; // ❌ 报错
    }
}

⚠️ 踩坑：只读属性只能赋值一次，且只能在声明它的类内部赋值（构造函数内）。clone 操作不会重置只读属性，所以无法用 clone $obj; $clone->readonly = newVal; 来"修改"。PHP 8.3 引入了 clone with 语法（尚在 RFC 阶段），目前可用工厂方法代替。

match 表达式与命名参数：日常必用的提效利器

这两个特性虽然不如 Fibers 那么炫酷，但在日常开发中出现频率极高，值得专门介绍。

match 表达式（PHP 8.0+）

match 是 switch 的严格类型版本：使用 === 比较，必须有返回值，不会 fall-through，未匹配时抛出 UnhandledMatchError。

<?php
// 旧写法 switch（PHP 7.x）
function getDiscount_old(string $userType): int {
    switch ($userType) {
        case 'vip':
            return 20;
        case 'member':
            return 10;
        default:
            return 0;
    }
}

// 新写法 match（PHP 8.0+）
function getDiscount(string $userType): int {
    return match($userType) {
        'vip'    => 20,
        'member' => 10,
        default  => 0,
    };
}

// match 可以匹配多个条件
$httpCode = 404;
$message = match(true) {
    $httpCode >= 500              => '服务器错误',
    $httpCode === 404             => '页面不存在',
    $httpCode === 401, $httpCode === 403 => '无权访问',
    $httpCode >= 200 && $httpCode < 300  => '成功',
    default                       => '未知状态',
};
echo $message;  // 输出: 页面不存在

命名参数（PHP 8.0+）

命名参数让函数调用更清晰，尤其是有多个可选参数时，无需记忆参数顺序。

<?php
// 旧写法：必须记住参数顺序，第 3、4、5 个参数是什么鬼？
$result = array_slice($array, 0, 5, true);

// 新写法：一目了然
$result = array_slice(array: $array, offset: 0, length: 5, preserve_keys: true);

// 在构造函数中特别好用（和 Constructor Promotion 组合）
class PaginatedQuery {
    public function __construct(
        public readonly string $table,
        public readonly int    $page    = 1,
        public readonly int    $perPage = 20,
        public readonly string $orderBy = 'created_at',
        public readonly string $order   = 'desc',
    ) {}
}

// 只传你关心的参数
$query = new PaginatedQuery(
    table:   'orders',
    perPage: 50,
    orderBy: 'total_amount',
);

Intersection Types：更精确的接口约束

PHP 8.1 引入交叉类型（Intersection Types），允许一个参数同时满足多个接口约束，不再需要为此创建空的组合接口。

<?php
interface Serializable {
    public function serialize(): string;
}

interface Loggable {
    public function toLog(): array;
}

interface Cacheable {
    public function cacheKey(): string;
    public function ttl(): int;
}

// 旧写法（PHP 8.0 以前）：必须创建一个组合接口
interface CacheableAndLoggable extends Cacheable, Loggable {}

function saveToCache(CacheableAndLoggable $entity): void {
    // ...
}

// 新写法（PHP 8.1+ 交叉类型）：直接用 & 组合
function saveToCache(Cacheable&Loggable $entity): void {
    $key  = $entity->cacheKey();
    $ttl  = $entity->ttl();
    $log  = $entity->toLog();
    
    // 存缓存 + 记日志
    echo "缓存 {$key}，TTL={$ttl}s\n";
}

// 实际类只需实现对应接口即可
class Order implements Cacheable, Loggable, Serializable {
    public function __construct(private string $id) {}
    
    public function cacheKey(): string { return "order:{$this->id}"; }
    public function ttl(): int { return 300; }
    public function toLog(): array { return ['order_id' => $this->id]; }
    public function serialize(): string { return json_encode(['id' => $this->id]); }
}

saveToCache(new Order('ORD-001'));  // ✅ Order 实现了 Cacheable 和 Loggable

⚠️ 踩坑：交叉类型不能和 Union 类型混用（如 A&B|C 会报错），也不能包含 null。返回类型同样支持交叉类型声明。

升级清单与兼容性检查

升级前必须做的几件事：

运行 php-compatibility-checker：composer require --dev phpcompatibility/php-compatibility，扫描项目中不兼容的写法
检查第三方库：composer require --dev roave/backward-compatibility-check
注意废弃函数：PHP 8.x 废弃了 utf8_encode/decode、部分 PCRE 函数，需要替换
错误处理变化：PHP 8.0 将很多 Warning 升级为了 TypeError 或 ValueError，需要修复类型不匹配问题

# 检查兼容性（以 PHP 8.2 为目标）
./vendor/bin/phpcs --standard=PHPCompatibility \
  --runtime-set testVersion 8.2 \
  --extensions=php \
  ./src/

# 使用 Rector 自动迁移旧代码
composer require --dev rector/rector
./vendor/bin/rector process src --set-list php82

升级 PHP 8.x 是一次值得投资的技术债偿还。Enum 减少了 30% 的状态相关 bug，只读属性让值对象的设计更加清晰，Fibers 则为将来拥抱异步编程打下基础。建议从 PHP 8.1 开始，把 Enum 和只读属性用起来，这两个特性学习成本最低、收益最高。

Ollama 本地部署大模型完全指南：从安装配置到实际应用

Fri, 03 Apr 2026 10:19:38 +0800

为什么选择 Ollama 在本地部署大模型？

近年来，随着 LLaMA、Mistral、Qwen 等开源大语言模型的涌现，越来越多的开发者希望在本地运行大模型，而不是依赖 OpenAI 等云服务。本地部署的优势显而易见：

数据隐私：代码、文档、敏感信息不离开本地机器
无调用费用：无需按 Token 计费，随意调用
离线可用：无网络也能正常使用
自定义模型：可以微调、量化、替换任意模型
低延迟：本地推理延迟通常低于远程 API

而 Ollama 正是让这一切变得极其简单的工具。它将模型下载、管理、推理服务全部封装成一个命令行工具，配合 REST API，可以无缝替换 OpenAI 接口。本文将从零开始，带你完整走通 Ollama 的安装、配置、模型管理，以及实际开发应用的全流程。

环境准备与安装

Ollama 支持 macOS、Linux 和 Windows（WSL2），以下以 Linux/macOS 为主，Windows 用户参考 WSL2 方案。

硬件要求

最低配置：8GB 内存，可运行 7B 量化模型（Q4）
推荐配置：16GB 内存，运行 13B Q4 模型流畅
GPU 加速：NVIDIA GPU（推荐 8GB+ 显存），支持 CUDA 11.8+
Apple Silicon：M1/M2/M3 Mac 天然支持，Metal 加速极快

安装步骤

Linux / macOS 一键安装：

# 官方安装脚本（推荐）
curl -fsSL https://ollama.com/install.sh | sh

# 安装完成后验证
ollama --version
# 输出：ollama version is 0.3.x

macOS 也可以通过 Homebrew 安装：

brew install ollama

Windows 用户下载安装包：https://ollama.com/download/windows

安装完成后，Ollama 会在后台以服务形式运行（默认监听 localhost:11434）。你可以手动控制服务：

# 启动服务（如果未自动启动）
ollama serve

# 查看服务状态
systemctl status ollama  # Linux systemd 系统

# 查看日志
journalctl -u ollama -f

下载与管理模型

Ollama 内置模型仓库，支持一键拉取主流开源模型。

常用模型推荐

llama3.2:3b - Meta 最新 Llama，3B 参数，内存占用约 2GB，速度极快
qwen2.5:7b - 阿里通义，中文能力强，7B Q4 约 5GB
mistral:7b - 法国 Mistral，代码能力优秀
deepseek-coder:6.7b - 专门针对代码优化，编程效果极佳
phi3:mini - 微软 Phi-3，3.8B 参数，效果超越同量级模型
gemma2:9b - Google Gemma2，综合能力强

模型下载与基本操作

# 下载模型（首次运行会自动下载）
ollama pull llama3.2:3b

# 查看已下载的模型
ollama list
# NAME              ID              SIZE    MODIFIED
# llama3.2:3b       a80c4f17acd5    2.0 GB  2 minutes ago

# 交互式对话（命令行）
ollama run llama3.2:3b
# >>> 输入你的问题

# 删除模型
ollama rm llama3.2:3b

# 查看模型详情
ollama show llama3.2:3b

⚠️ 踩坑记录：首次下载大模型（如 70B）时可能需要几十分钟，请确保磁盘空间充足。模型默认存储在 ~/.ollama/models，可以通过环境变量 OLLAMA_MODELS 修改存储路径：

# 修改模型存储路径（加入 ~/.bashrc 或 ~/.zshrc）
export OLLAMA_MODELS=/data/ollama-models

# 重启服务生效
sudo systemctl restart ollama

通过 REST API 调用模型

Ollama 提供了兼容 OpenAI 格式的 REST API，这让它可以无缝接入各种工具链。

基础 API 调用

# 使用 curl 调用（流式输出）
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2:3b",
  "prompt": "用 Python 写一个快速排序算法",
  "stream": false
}'

# 返回示例
{
  "model": "llama3.2:3b",
  "created_at": "2024-01-01T00:00:00Z",
  "response": "def quicksort(arr):\n    if len(arr)

OpenAI 兼容接口（推荐）

Ollama 还提供了 /v1/chat/completions 兼容接口，直接替换 OpenAI SDK：

from openai import OpenAI

# 只需替换 base_url，无需修改其他代码！
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # 随意填写，本地不校验
)

response = client.chat.completions.create(
    model="llama3.2:3b",
    messages=[
        {"role": "system", "content": "你是一个专业的 Python 开发者"},
        {"role": "user", "content": "帮我实现一个二分查找函数"}
    ]
)
print(response.choices[0].message.content)

Python 原生 SDK 调用

pip install ollama

# 使用示例
import ollama

# 简单对话
response = ollama.chat(model='llama3.2:3b', messages=[
    {'role': 'user', 'content': '解释一下 Python 的 GIL 锁'}
])
print(response['message']['content'])

# 流式输出
stream = ollama.chat(
    model='qwen2.5:7b',
    messages=[{'role': 'user', 'content': '写一篇关于 AI 的短文'}],
    stream=True,
)
for chunk in stream:
    print(chunk['message']['content'], end='', flush=True)

自定义 Modelfile：创建专属模型

Ollama 支持通过 Modelfile 自定义模型行为，类似于 Docker 的 Dockerfile。

Modelfile 基本结构

# 创建 Modelfile
cat > Modelfile

参数说明

temperature：控制随机性，0.1-0.3 适合代码任务，0.7-0.9 适合创意写作
top_p：核采样，一般保持 0.9
num_ctx：上下文窗口大小，越大越吃内存，一般 4096-8192
repeat_penalty：重复惩罚，防止模型循环输出，推荐 1.1

⚠️ 踩坑记录：系统提示词中如果含有中文引号或特殊字符，Modelfile 解析可能出错。建议使用三引号 """ 包裹，并避免在提示词中使用反斜杠。

与主流开发工具集成

VS Code + Continue 插件

Continue 是最受欢迎的 VS Code AI 编程插件，支持本地 Ollama 模型：

在 VS Code 扩展市场安装 Continue
打开配置文件 ~/.continue/config.json
添加 Ollama 模型配置：

{
  "models": [
    {
      "title": "Qwen2.5 7B (Local)",
      "provider": "ollama",
      "model": "qwen2.5:7b",
      "apiBase": "http://localhost:11434"
    },
    {
      "title": "DeepSeek Coder (Local)",
      "provider": "ollama",
      "model": "deepseek-coder:6.7b",
      "apiBase": "http://localhost:11434"
    }
  ],
  "tabAutocompleteModel": {
    "title": "Autocomplete",
    "provider": "ollama",
    "model": "qwen2.5-coder:1.5b"
  }
}

Open WebUI：本地 ChatGPT 界面

Open WebUI 提供了类似 ChatGPT 的 Web 界面，Docker 一键部署：

# 前提：Ollama 已在本地运行
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

# 访问 http://localhost:3000

⚠️ 踩坑记录：Docker 容器内无法直接访问宿主机的 Ollama 服务。需要用 --add-host=host.docker.internal:host-gateway，然后在 Open WebUI 设置中将 Ollama 地址改为 http://host.docker.internal:11434。

LangChain 集成

pip install langchain-community

from langchain_community.llms import Ollama
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

# 初始化 Ollama LLM
llm = Ollama(model="qwen2.5:7b", base_url="http://localhost:11434")

# 创建提示模板
prompt = PromptTemplate(
    input_variables=["topic"],
    template="请用中文写一篇关于{topic}的技术博客文章大纲，包含5个主要章节。"
)

# 创建链
chain = LLMChain(llm=llm, prompt=prompt)

# 执行
result = chain.run(topic="微服务架构设计模式")
print(result)

性能优化与调优技巧

GPU 加速配置

如果你有 NVIDIA GPU，Ollama 会自动检测并使用。验证 GPU 是否被使用：

# 运行模型时查看 GPU 使用情况
watch -n1 nvidia-smi

# 或在运行时检查 Ollama 日志
journalctl -u ollama -f | grep "cuda\|gpu"

强制使用指定 GPU（多卡环境）：

# 只使用第 0 块 GPU
CUDA_VISIBLE_DEVICES=0 ollama serve

# 使用多块 GPU（需要 Ollama 0.2.0+）
CUDA_VISIBLE_DEVICES=0,1 ollama serve

内存优化

对于内存不足的情况，可以使用更高压缩比的量化模型：

model:Q8_0 - 8bit 量化，质量最好，内存约原始的 50%
model:Q4_K_M - 4bit 量化，推荐平衡版，内存约原始的 25%
model:Q3_K_S - 3bit 量化，最省内存，质量有损失

# 下载特定量化版本
ollama pull qwen2.5:7b-instruct-q4_K_M

# 查看不同量化版本
ollama list | grep qwen

并发请求配置

# 设置最大并发请求数（默认 1）
OLLAMA_NUM_PARALLEL=4 ollama serve

# 设置最大加载模型数量
OLLAMA_MAX_LOADED_MODELS=3 ollama serve

# 写入 systemd 服务配置（永久生效）
sudo systemctl edit ollama
# 添加：
[Service]
Environment="OLLAMA_NUM_PARALLEL=4"
Environment="OLLAMA_MAX_LOADED_MODELS=2"

实战案例：构建本地 AI 代码助手

下面我们来实现一个实用的本地 AI 代码助手，支持代码审查、Bug 修复和文档生成：

import ollama
import sys
from pathlib import Path

class LocalCodeAssistant:
    def __init__(self, model="qwen2.5:7b"):
        self.model = model
        self.client = ollama.Client(host="http://localhost:11434")
    
    def review_code(self, code: str, language: str = "Python") -> str:
        """代码审查"""
        prompt = f"""请审查以下 {language} 代码，指出：
1. 潜在的 Bug
2. 安全问题
3. 性能优化点
4. 代码风格问题

代码：
```{language.lower()}
{code}
```

请用中文回答，格式清晰。"""
        
        response = self.client.chat(
            model=self.model,
            messages=[{"role": "user", "content": prompt}]
        )
        return response["message"]["content"]
    
    def generate_docstring(self, func_code: str) -> str:
        """生成函数文档"""
        prompt = f"""为以下函数生成详细的 docstring（Google 风格）：

{func_code}

只返回 docstring 内容，不要包含函数本身。"""
        
        response = self.client.chat(
            model=self.model,
            messages=[{"role": "user", "content": prompt}]
        )
        return response["message"]["content"]
    
    def fix_bug(self, code: str, error_msg: str) -> str:
        """修复 Bug"""
        prompt = f"""以下代码出现了错误，请帮我修复：

代码：
```python
{code}
```

错误信息：
{error_msg}

请提供修复后的完整代码，并解释修改原因。"""
        
        response = self.client.chat(
            model=self.model,
            messages=[{"role": "user", "content": prompt}]
        )
        return response["message"]["content"]


# 使用示例
if __name__ == "__main__":
    assistant = LocalCodeAssistant(model="qwen2.5:7b")
    
    # 示例：代码审查
    sample_code = """
def get_user_data(user_id):
    conn = sqlite3.connect('users.db')
    cursor = conn.cursor()
    query = f"SELECT * FROM users WHERE id = {user_id}"
    cursor.execute(query)
    return cursor.fetchone()
"""
    
    print("=== 代码审查结果 ===")
    result = assistant.review_code(sample_code)
    print(result)

运行效果：模型会准确指出上述代码存在 SQL 注入漏洞，并提供参数化查询的修复方案。

常见问题与解决方案

问题：ollama: command not found
解决：检查 /usr/local/bin/ollama 是否存在，重新执行安装脚本，或手动添加 PATH。
问题：模型加载缓慢，CPU 使用率 100%
解决：确认 GPU 驱动已安装（nvidia-smi），Ollama 会自动使用 GPU。如果是 CPU 推理，属于正常现象。
问题：Error: model not found
解决：先执行 ollama pull 模型名 下载模型，或检查模型名拼写（区分大小写）。
问题：内存不足，推理崩溃
解决：换用更小参数量或更高压缩比的量化模型，如 :3b-q4_0 版本。
问题：多轮对话上下文丢失
解决：使用 /api/chat 接口并维护完整 messages 历史，而非 /api/generate。
问题：Open WebUI 连接不上 Ollama
解决：检查 Ollama 是否监听在 0.0.0.0，可设置 OLLAMA_HOST=0.0.0.0 环境变量。

至此，你已经掌握了 Ollama 从安装到实际应用的完整流程。本地大模型部署的门槛已经大幅降低，无论是个人开发者还是企业团队，都可以用极低的成本搭建私有 AI 基础设施。建议从 qwen2.5:7b 或 llama3.2:3b 开始体验，根据实际需求逐步调优。

PHP 8.3 新特性实战：Typed Constants、readonly 改进与迁移指南

Thu, 02 Apr 2026 08:05:27 +0800

为什么要升级到 PHP 8.3？

PHP 8.3 于 2023 年 11 月正式发布，支持周期到 2027 年底。相比 8.2，它带来的不只是性能微调——多项语法特性直接影响日常编码质量。如果你还在犹豫是否升级，看完本文的实战案例，相信你会迫不及待地打开终端。

本文聚焦以下几个最值得关注的特性：

类型化类常量（Typed Class Constants）
readonly 属性在匿名类中的改进
新增 json_validate() 函数
动态类常量获取语法
新的 Randomizer 扩展 API

类型化类常量：终于可以给常量加类型了

PHP 8.2 及以前，类常量没有类型声明，任何类型都能赋值，子类覆写时也不会有类型检查。PHP 8.3 引入了类型化常量，解决了这个长期痛点。

旧写法（PHP 8.2）：

<?php
class Status {
    const ACTIVE = 1;       // 没有类型，子类可以随意覆写
    const NAME   = 'active';
}

class ExtendedStatus extends Status {
    const ACTIVE = 'yes';   // PHP 8.2 不会报错，但语义混乱！
}

新写法（PHP 8.3）：

<?php
class Status {
    const int    ACTIVE = 1;
    const string NAME   = 'active';
    const float  RATIO  = 0.95;
    const bool   IS_ENABLED = true;
}

// 子类覆写类型不匹配，直接报 Fatal Error
class ExtendedStatus extends Status {
    const int ACTIVE = 'yes';  // Fatal: Cannot use string as value for constant of type int
}

实战建议：

在 DTO、枚举类、配置类中优先使用类型化常量，可以在 CI 阶段就发现类型错误
支持的类型包括：int、float、string、bool、array、null，以及联合类型 int|string
接口（interface）中的常量同样支持类型声明，实现类必须遵守类型约束

<?php
interface HasVersion {
    const string VERSION = '1.0.0';
}

class App implements HasVersion {
    const string VERSION = '2.0.0'; // OK
    // const int VERSION = 2;       // Fatal Error
}

json_validate()：再也不用 json_decode 试错了

过去验证一个字符串是否是合法 JSON，我们通常这样做：

<?php
// 旧方案：解码再检查
function isValidJson(string $json): bool {
    json_decode($json);
    return json_last_error() === JSON_ERROR_NONE;
}

这个方案有个显著缺点：json_decode 会构建完整的 PHP 数据结构，对于只需要验证合法性的场景，白白消耗了内存和 CPU。

PHP 8.3 新增了 json_validate()，只做语法检查，不构建数据结构：

<?php
// 新方案：只验证，不解析
$payload = '{"user": "alice", "age": 30}';

if (json_validate($payload)) {
    $data = json_decode($payload, true);
    // 处理数据...
} else {
    throw new InvalidArgumentException('Invalid JSON payload');
}

// 也支持深度限制，防止嵌套过深的恶意输入
json_validate($payload, depth: 5);     // 最大嵌套 5 层
json_validate($payload, flags: JSON_INVALID_UTF8_IGNORE); // 忽略无效 UTF-8

踩坑记录： json_validate() 在验证失败时不会设置 json_last_error()，也没有返回错误信息。如果你需要知道具体错误，还是得用 json_decode + json_last_error_msg()。

动态类常量获取：告别硬编码的常量名

PHP 8.3 之前，访问类常量必须用字面量名称，无法使用变量：

<?php
class Color {
    const RED   = '#FF0000';
    const GREEN = '#00FF00';
    const BLUE  = '#0000FF';
}

// PHP 8.2：不能用变量访问常量
$name = 'RED';
// echo Color::$name;  // 这是访问静态属性，不是常量！
constant('Color::' . $name); // 只能用 constant() 函数，略显丑陋

// PHP 8.3：支持动态常量名
echo Color::{$name}; // 输出 #FF0000

真实使用场景——根据配置动态读取常量：

<?php
class HttpStatus {
    const int OK        = 200;
    const int NOT_FOUND = 404;
    const int ERROR     = 500;
}

function getStatusCode(string $statusName): int {
    return HttpStatus::{$statusName};
}

echo getStatusCode('OK');        // 200
echo getStatusCode('NOT_FOUND'); // 404

注意： 如果常量不存在，会抛出 Error，使用前建议加 defined() 检查或 try-catch。

从 PHP 8.2 迁移的注意事项与升级步骤

实际项目升级到 PHP 8.3，按以下步骤操作可以大幅降低风险：

第一步：本地安装 PHP 8.3 并跑测试

# Ubuntu/Debian
sudo add-apt-repository ppa:ondrej/php
sudo apt install php8.3 php8.3-cli php8.3-fpm php8.3-mbstring php8.3-xml php8.3-curl

# macOS (Homebrew)
brew install php@8.3
brew link php@8.3 --force

# 验证版本
php -v

第二步：检查废弃特性

# 用 PHP_CodeSniffer 扫描弃用特性
composer require --dev squizlabs/php_codesniffer
./vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.3 src/

第三步：关注几个常见 Breaking Changes

ReflectionProperty::setValue() 的参数已更新，第一个参数不再是可选的
静态变量在 trait 方法中的处理方式有所调整，多个类使用同一 trait 时每个类维护独立的静态变量
部分内置函数（如 str_pad）对类型参数更严格，确保传入正确类型

第四步：Composer 依赖更新

# 检查依赖是否支持 PHP 8.3
composer why-not php 8.3

# 更新全部依赖
composer update --with-all-dependencies

按照这四步走，大多数 Laravel/Symfony 项目都能在半天内完成升级，升级后你立刻就能享受 PHP 8.3 带来的约 5~10% 的性能提升和更严格的类型安全。

Jetpack Compose 实战：从零到高性能 Android UI 的完整指南

Tue, 31 Mar 2026 08:07:23 +0800

Jetpack Compose 已经发布正式版超过两年，但很多 Android 开发者在实际项目中落地时仍然踩了不少坑：性能抖动、状态管理混乱、与旧 View 体系混用问题频发。本文基于真实项目经验，从「能跑」到「跑得好」，系统梳理 Compose 实战中的核心技巧与常见陷阱。

一、为什么要用 Jetpack Compose？先看清楚再下手

很多团队是"追风"式迁移到 Compose，结果踩坑后悔。在动手之前，先明确几点：

优势：声明式 UI、更少的样板代码、与 Kotlin 协程天然配合、热重载（Live Edit）支持
当前局限：部分动画复杂场景性能弱于 View、与部分第三方 View 库兼容性差、编译速度较慢
适合场景：新项目、纯 Kotlin 栈、以列表/表单/详情页为主的 UI

如果你的项目大量依赖 Google Maps、WebView、自定义 SurfaceView，短期内不建议强行全迁移。

二、项目结构设计：从 MVI 架构角度组织 Compose 代码

Compose 最适合配合 MVI（Model-View-Intent）架构使用。推荐目录结构如下：

app/
├── ui/
│   ├── screen/
│   │   ├── home/
│   │   │   ├── HomeScreen.kt        # UI 入口，只负责组合组件
│   │   │   ├── HomeViewModel.kt     # 持有 UiState，处理事件
│   │   │   └── HomeUiState.kt       # 密封类定义页面状态
│   │   └── detail/
│   ├── component/                   # 可复用的原子组件
│   └── theme/                       # 主题、颜色、字体
├── domain/                          # 业务逻辑层（纯 Kotlin）
└── data/                            # 数据层

定义 UiState 时用 sealed class 或 data class：

// HomeUiState.kt
sealed class HomeUiState {
    object Loading : HomeUiState()
    data class Success(val items: List<ArticleItem>) : HomeUiState()
    data class Error(val message: String) : HomeUiState()
}

// HomeViewModel.kt
class HomeViewModel(private val repo: ArticleRepository) : ViewModel() {
    private val _uiState = MutableStateFlow<HomeUiState>(HomeUiState.Loading)
    val uiState: StateFlow<HomeUiState> = _uiState.asStateFlow()

    init {
        loadArticles()
    }

    fun loadArticles() {
        viewModelScope.launch {
            _uiState.value = HomeUiState.Loading
            try {
                val items = repo.getArticles()
                _uiState.value = HomeUiState.Success(items)
            } catch (e: Exception) {
                _uiState.value = HomeUiState.Error(e.message ?: "未知错误")
            }
        }
    }
}

Screen 层只负责消费状态，不写任何业务逻辑：

@Composable
fun HomeScreen(viewModel: HomeViewModel = hiltViewModel()) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    when (uiState) {
        is HomeUiState.Loading -> LoadingIndicator()
        is HomeUiState.Success -> ArticleList(items = (uiState as HomeUiState.Success).items)
        is HomeUiState.Error -> ErrorView(message = (uiState as HomeUiState.Error).message) {
            viewModel.loadArticles()
        }
    }
}

三、性能优化：避免不必要的重组（Recomposition）

这是 Compose 实战中最容易踩的坑。每次状态变化都可能触发重组，如果组件设计不当，会导致严重的性能问题。

3.1 用 remember 和 derivedStateOf 缓存计算

// ❌ 错误写法：每次重组都重新计算
@Composable
fun ArticleList(items: List<ArticleItem>) {
    val sortedItems = items.sortedByDescending { it.publishTime } // 每次重组都排序！
    LazyColumn {
        items(sortedItems) { ArticleCard(it) }
    }
}

// ✅ 正确写法：用 remember 缓存，derivedStateOf 监听依赖变化
@Composable
fun ArticleList(items: List<ArticleItem>) {
    val sortedItems by remember(items) {
        derivedStateOf { items.sortedByDescending { it.publishTime } }
    }
    LazyColumn {
        items(sortedItems, key = { it.id }) { ArticleCard(it) }
    }
}

3.2 stable 和 immutable 注解减少重组范围

// ❌ List 是不稳定类型，会导致父组件重组时子组件一起重组
data class UserProfile(val name: String, val tags: List<String>)

// ✅ 使用 @Immutable 标注数据类为稳定类型
@Immutable
data class UserProfile(val name: String, val tags: List<String>)

或者使用 Kotlin 不可变集合库 `kotlinx.collections.immutable`：

// build.gradle.kts
implementation("org.jetbrains.kotlinx:kotlinx-collections-immutable:0.3.7")

// 使用
data class UserProfile(
    val name: String,
    val tags: ImmutableList<String>  // 稳定类型，Compose 可感知
)

3.3 用 Layout Inspector 实际测量重组次数

Android Studio 的 Layout Inspector 可以实时显示每个 Composable 的重组次数。步骤：

运行 Debug 包，连接设备
菜单：View → Tool Windows → Layout Inspector
勾选「Show recomposition counts」
操作 UI，观察红色高亮（重组频繁）的组件

四、与旧 View 体系混用：AndroidView 和 ComposeView 的正确姿势

实际项目中完全不用 View 几乎不可能，以下是混用的标准写法：

4.1 在 Compose 中嵌入 View：AndroidView

@Composable
fun WebViewComposable(url: String) {
    AndroidView(
        factory = { context ->
            WebView(context).apply {
                webViewClient = WebViewClient()
                settings.javaScriptEnabled = true
            }
        },
        update = { webView ->
            // update 在每次重组时调用，注意避免重复加载
            webView.loadUrl(url)
        },
        modifier = Modifier.fillMaxSize()
    )
}

⚠️ 注意：`update` lambda 会在每次 Composable 重组时执行，如果 `url` 没变化却重新 loadUrl 会导致页面闪烁。应该用 `LaunchedEffect` 或在 update 中判断：

update = { webView ->
    if (webView.url != url) {  // 只有 URL 变化才加载
        webView.loadUrl(url)
    }
}

4.2 在 XML 布局中嵌入 Compose：ComposeView

<!-- fragment_profile.xml -->
<LinearLayout ...>
    <TextView android:id="@+id/title" ... />
    <androidx.compose.ui.platform.ComposeView
        android:id="@+id/compose_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />
</LinearLayout>

// ProfileFragment.kt
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    binding.composeView.apply {
        setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
        setContent {
            MaterialTheme {
                ProfileCard(viewModel = viewModel)
            }
        }
    }
}

⚠️ 必须设置 `setViewCompositionStrategy`，否则在 Fragment 中会有内存泄漏风险。

五、导航：Navigation Compose 实战与深链接配置

推荐用 Navigation Compose 统一管理路由，定义路由常量避免字符串硬编码：

// NavRoutes.kt
object NavRoutes {
    const val HOME = "home"
    const val ARTICLE_DETAIL = "article/{articleId}"
    const val PROFILE = "profile"

    fun articleDetail(id: String) = "article/$id"
}

// AppNavGraph.kt
@Composable
fun AppNavGraph(navController: NavHostController) {
    NavHost(navController, startDestination = NavRoutes.HOME) {
        composable(NavRoutes.HOME) {
            HomeScreen(
                onArticleClick = { id ->
                    navController.navigate(NavRoutes.articleDetail(id))
                }
            )
        }
        composable(
            route = NavRoutes.ARTICLE_DETAIL,
            arguments = listOf(navArgument("articleId") { type = NavType.StringType }),
            deepLinks = listOf(navDeepLink { uriPattern = "myapp://article/{articleId}" })
        ) { backStackEntry ->
            val articleId = backStackEntry.arguments?.getString("articleId") ?: return@composable
            ArticleDetailScreen(articleId = articleId)
        }
    }
}

六、主题系统：Material3 动态配色的正确接入方式

// Theme.kt
@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,  // Android 12+ 动态配色
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context)
            else dynamicLightColorScheme(context)
        }
        darkTheme -> DarkColorScheme
        else -> LightColorScheme
    }

    MaterialTheme(
        colorScheme = colorScheme,
        typography = AppTypography,
        content = content
    )
}

七、实战踩坑总结与最佳实践清单

以下是从真实项目中整理的高频坑点：

❌ 不要在 Composable 函数中直接创建 ViewModel（用 hiltViewModel() 或 viewModel()）
❌ 不要在 Composable 中直接读写 SharedPreferences（应该通过 ViewModel/Repository 层）
❌ 不要用 GlobalScope 启动协程（Compose 侧用 LaunchedEffect，ViewModel 用 viewModelScope）
✅ LazyColumn 的 items 必须提供 key 参数，避免列表更新时的全量重组
✅ 图片加载推荐 Coil（完整 Compose 支持）：AsyncImage(model = url, contentDescription = null)
✅ 需要访问 Context 时用 LocalContext.current，不要把 Context 传入 ViewModel
✅ 列表分页用 Paging 3 + collectAsLazyPagingItems()，官方 Compose 扩展很成熟

// 分页列表标准写法
@Composable
fun ArticlePagingList(viewModel: HomeViewModel = hiltViewModel()) {
    val pagingItems = viewModel.articlePager.collectAsLazyPagingItems()

    LazyColumn {
        items(
            count = pagingItems.itemCount,
            key = pagingItems.itemKey { it.id }
        ) { index ->
            val item = pagingItems[index]
            if (item != null) ArticleCard(item)
            else ArticleCardPlaceholder()
        }

        when (val loadState = pagingItems.loadState.append) {
            is LoadState.Loading -> item { CircularProgressIndicator() }
            is LoadState.Error -> item { 
                RetryButton(onClick = { pagingItems.retry() })
            }
            else -> {}
        }
    }
}

Jetpack Compose 的学习曲线主要在于思维转换，从「如何操作 View」变为「如何描述状态」。遇到性能问题不要慌，先用 Layout Inspector 定位重组热点，再针对性优化。实际上大多数日常 UI 场景，按本文的结构设计走，不做任何特殊优化也能有很好的性能表现。

PHP 项目重构实战：Repository + Service + Controller 三层架构落地指南

Sun, 29 Mar 2026 08:04:59 +0800

为什么你的 PHP 代码越来越难维护？

很多 PHP 项目在初期写得飞快，但随着功能迭代，代码库逐渐变成一个"屎山"——数据库查询散落在各处、业务逻辑和展示层混在一起、测试几乎无从下手。这不是 PHP 语言的问题，而是缺少分层架构的必然结果。

本文将以一个电商订单模块为例，手把手带你把一段典型的"意大利面条"代码重构为清晰的三层架构（Repository + Service + Controller），让你的代码可读、可测、可维护。

第一步：认识问题——原始代码长什么样

先看一段典型的"一把梭"PHP 代码，很多中小项目都长这样：

<?php// OrderController.php（反面教材）class OrderController {    public function create() {        $db = new PDO('mysql:host=localhost;dbname=shop', 'root', '123456');        $userId = $_POST['user_id'];        $productId = $_POST['product_id'];        $qty = (int)$_POST['qty'];        // 直接查库存        $stmt = $db->prepare("SELECT stock FROM products WHERE id = ?");        $stmt->execute([$productId]);        $product = $stmt->fetch();        if ($product['stock'] < $qty) {            echo json_encode(['error' => '库存不足']);            return;        }        // 扣库存        $db->prepare("UPDATE products SET stock = stock - ? WHERE id = ?")           ->execute([$qty, $productId]);        // 写订单        $db->prepare("INSERT INTO orders (user_id, product_id, qty, status) VALUES (?,?,?,'pending')")           ->execute([$userId, $productId, $qty]);        // 发邮件（直接塞在这里）        mail('admin@example.com', '新订单', "用户{$userId}下单了{$qty}个商品{$productId}");        echo json_encode(['success' => true]);    }}

这段代码有哪些问题？

数据库连接硬编码，密码暴露在代码里
SQL 语句散落在 Controller，无法复用
业务逻辑（库存校验、扣减）和 HTTP 层混在一起
发邮件是副作用，单元测试根本无法隔离
任何改动都可能牵一发而动全身

第二步：分层设计——Repository + Service + Controller

我们采用经典的三层架构：

Repository 层：只负责数据库操作，封装所有 SQL，返回领域对象或数组
Service 层：核心业务逻辑，编排 Repository，处理事务和规则
Controller 层：只负责解析 HTTP 请求、调用 Service、返回响应

目录结构如下：

app/├── Controllers/│   └── OrderController.php├── Services/│   └── OrderService.php├── Repositories/│   ├── OrderRepository.php│   └── ProductRepository.php└── Models/    └── Order.php

第三步：实现 Repository 层

Repository 只做一件事：数据库读写。它不包含任何业务逻辑。

<?php// Repositories/ProductRepository.phpclass ProductRepository {    public function __construct(private PDO $db) {}    public function findById(int $id): ?array {        $stmt = $this->db->prepare("SELECT * FROM products WHERE id = ?");        $stmt->execute([$id]);        return $stmt->fetch(PDO::FETCH_ASSOC) ?: null;    }    public function decrementStock(int $productId, int $qty): void {        $this->db->prepare(            "UPDATE products SET stock = stock - ? WHERE id = ? AND stock >= ?"        )->execute([$qty, $productId, $qty]);    }}// Repositories/OrderRepository.phpclass OrderRepository {    public function __construct(private PDO $db) {}    public function create(int $userId, int $productId, int $qty): int {        $stmt = $this->db->prepare(            "INSERT INTO orders (user_id, product_id, qty, status, created_at) VALUES (?,?,?,'pending',NOW())"        );        $stmt->execute([$userId, $productId, $qty]);        return (int)$this->db->lastInsertId();    }}

踩坑记录：decrementStock 中故意在 WHERE 加了 AND stock >= ?，这是一个乐观锁技巧——如果并发场景下库存已被其他请求扣掉，这条 SQL 会影响 0 行，配合 rowCount() 检查可以避免超卖。

第四步：实现 Service 层

Service 层是业务大脑，负责编排 Repository 并处理事务：

<?php// Services/OrderService.phpclass OrderService {    public function __construct(        private PDO $db,        private ProductRepository $productRepo,        private OrderRepository $orderRepo,        private MailerInterface $mailer  // 依赖注入，方便 mock    ) {}    public function createOrder(int $userId, int $productId, int $qty): int {        $product = $this->productRepo->findById($productId);        if (!$product) {            throw new \RuntimeException('商品不存在');        }        if ($product['stock'] < $qty) {            throw new \DomainException('库存不足，当前库存：' . $product['stock']);        }        $this->db->beginTransaction();        try {            $this->productRepo->decrementStock($productId, $qty);            // 验证扣减是否成功（防超卖）            $updated = $this->db->query("SELECT ROW_COUNT()")->fetchColumn();            if ($updated == 0) {                throw new \DomainException('库存扣减失败，请重试');            }            $orderId = $this->orderRepo->create($userId, $productId, $qty);            $this->db->commit();            // 发通知（在事务外，失败不影响下单）            $this->mailer->send('admin@example.com', '新订单', "订单#{$orderId}已创建");            return $orderId;        } catch (\Exception $e) {            $this->db->rollBack();            throw $e;        }    }}

关键设计点：发邮件放在 commit() 之后、事务之外，这样邮件失败不会导致订单回滚。

第五步：精简 Controller

重构后的 Controller 只做三件事：解析请求、调用 Service、返回响应。

<?php// Controllers/OrderController.phpclass OrderController {    public function __construct(private OrderService $orderService) {}    public function create(Request $request): Response {        try {            $orderId = $this->orderService->createOrder(                userId: (int)$request->input('user_id'),                productId: (int)$request->input('product_id'),                qty: (int)$request->input('qty')            );            return Response::json(['order_id' => $orderId], 201);        } catch (\DomainException $e) {            return Response::json(['error' => $e->getMessage()], 422);        } catch (\Exception $e) {            // 记录日志，不暴露内部错误            logger()->error('下单失败', ['exception' => $e]);            return Response::json(['error' => '服务异常，请稍后重试'], 500);        }    }}

注意异常处理的分层：DomainException 是业务异常，直接告知用户；其他未知异常记录日志后返回通用错误，绝不暴露内部堆栈给客户端。

重构前后对比与总结

经过这次重构，代码的可维护性有了质的提升。以下是直观对比：

可测试性：Service 层通过依赖注入，单元测试时可以 mock Repository 和 Mailer，无需真实数据库
可复用性：ProductRepository::findById 可以被多个 Service 复用，不再重复写 SQL
可读性：每个类职责单一，新人接手代码时一眼知道去哪里找什么
防超卖：通过乐观锁 + ROW_COUNT 双重保障，解决了原始代码中的并发超卖问题

这套架构不依赖任何框架，在原生 PHP 项目或 Laravel、Symfony 等框架中均可应用。下一步可以继续引入 DTO（Data Transfer Object）来规范数据传递，或者配合 PHP 8.1 的枚举类型来强化订单状态管理。

好的架构不是一步到位的，但每一次小重构都在让代码变得更健康。

Android Jetpack Compose 实战：从零构建现代化 UI 组件库

Sat, 28 Mar 2026 08:10:48 +0800

Jetpack Compose 已经成为 Android 开发的主流 UI 框架，Google 官方也在不断推动开发者从传统 View 体系迁移到 Compose。然而，很多团队在实际落地时面临一个共同问题：如何设计一套可维护、可复用的组件库，而不是到处复制粘贴代码？

本文将带你从零构建一套团队级的 Compose UI 组件库，涵盖主题系统、常用组件封装、动画效果和性能踩坑。所有代码均基于 Compose 1.6.x + Material3，可直接应用到生产项目。

一、项目结构与模块划分

在开始写组件之前，先确定好目录结构。一个合理的组件库模块应该像这样组织：

ui-components/
├── src/main/java/com/yourapp/ui/
│   ├── theme/
│   │   ├── Color.kt          # 颜色系统
│   │   ├── Typography.kt     # 字体系统
│   │   ├── Shape.kt          # 形状系统
│   │   └── Theme.kt          # 主题入口
│   ├── components/
│   │   ├── button/
│   │   │   ├── AppButton.kt
│   │   │   └── IconButton.kt
│   │   ├── card/
│   │   │   └── AppCard.kt
│   │   ├── input/
│   │   │   ├── AppTextField.kt
│   │   │   └── SearchBar.kt
│   │   └── feedback/
│   │       ├── AppToast.kt
│   │       └── LoadingOverlay.kt
│   └── preview/
│       └── ComponentPreview.kt   # 统一 Preview 配置

这种结构的好处是：每个组件有独立目录，便于多人协作；theme 层统一管理设计 token；preview 集中管理，方便 UI Review。

二、主题系统设计——设计 Token 的正确实践

很多项目直接用硬编码的颜色值，这在换肤或品牌升级时会是噩梦。正确做法是建立设计 Token 体系：

// Color.kt
val Primary = Color(0xFF1976D2)
val PrimaryContainer = Color(0xFFBBDEFB)
val OnPrimary = Color(0xFFFFFFFF)
val Error = Color(0xFFB00020)
val Surface = Color(0xFFFAFAFA)

// 定义完整的 ColorScheme
val LightColorScheme = lightColorScheme(
    primary = Primary,
    primaryContainer = PrimaryContainer,
    onPrimary = OnPrimary,
    error = Error,
    surface = Surface,
    // ... 其他颜色
)

val DarkColorScheme = darkColorScheme(
    primary = Color(0xFF90CAF9),
    primaryContainer = Color(0xFF1565C0),
    onPrimary = Color(0xFF003087),
    // ... 暗色适配
)

// Theme.kt
@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = false,  // Android 12+ 动态取色
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context)
            else dynamicLightColorScheme(context)
        }
        darkTheme -> DarkColorScheme
        else -> LightColorScheme
    }

    MaterialTheme(
        colorScheme = colorScheme,
        typography = AppTypography,
        shapes = AppShapes,
        content = content
    )
}

踩坑记录：不要直接在组件内调用 MaterialTheme.colorScheme.primary 来硬编码组件颜色，而是通过参数传入或使用 LocalContentColor。这样组件才能真正跟随主题变化。

三、Button 组件封装——状态与样式分离

官方的 Button 已经足够好用，但在项目中往往需要统一 loading 状态、disabled 样式和点击防抖。来看封装后的效果：

// AppButton.kt
@Composable
fun AppButton(
    text: String,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    loading: Boolean = false,
    buttonType: ButtonType = ButtonType.Primary,
    leadingIcon: ImageVector? = null
) {
    val containerColor = when (buttonType) {
        ButtonType.Primary -> MaterialTheme.colorScheme.primary
        ButtonType.Secondary -> MaterialTheme.colorScheme.secondary
        ButtonType.Danger -> MaterialTheme.colorScheme.error
        ButtonType.Ghost -> Color.Transparent
    }

    Button(
        onClick = onClick,
        modifier = modifier.defaultMinSize(minHeight = 48.dp),
        enabled = enabled && !loading,
        colors = ButtonDefaults.buttonColors(
            containerColor = containerColor,
            disabledContainerColor = containerColor.copy(alpha = 0.38f)
        ),
        shape = MaterialTheme.shapes.medium
    ) {
        AnimatedContent(
            targetState = loading,
            transitionSpec = {
                fadeIn() togetherWith fadeOut()
            },
            label = "button_content"
        ) { isLoading ->
            if (isLoading) {
                CircularProgressIndicator(
                    modifier = Modifier.size(18.dp),
                    color = contentColorFor(containerColor),
                    strokeWidth = 2.dp
                )
            } else {
                Row(
                    verticalAlignment = Alignment.CenterVertically,
                    horizontalArrangement = Arrangement.spacedBy(8.dp)
                ) {
                    leadingIcon?.let {
                        Icon(imageVector = it, contentDescription = null, modifier = Modifier.size(18.dp))
                    }
                    Text(text = text)
                }
            }
        }
    }
}

enum class ButtonType { Primary, Secondary, Danger, Ghost }

使用示例：

var isLoading by remember { mutableStateOf(false) }

AppButton(
    text = "提交",
    onClick = {
        isLoading = true
        viewModel.submit { isLoading = false }
    },
    loading = isLoading,
    leadingIcon = Icons.Default.Send
)

点击防抖处理：在快速点击场景下，可以在 ViewModel 层控制，也可以在组件内用 debounce 包装 onClick：

fun Modifier.clickDebounced(
    debounceTime: Long = 500L,
    onClick: () -> Unit
): Modifier = composed {
    var lastClickTime by remember { mutableStateOf(0L) }
    this.clickable {
        val currentTime = System.currentTimeMillis()
        if (currentTime - lastClickTime >= debounceTime) {
            lastClickTime = currentTime
            onClick()
        }
    }
}

四、TextField 封装——统一错误状态与焦点管理

表单场景是 Compose 的高频痛点。官方 OutlinedTextField 用起来没问题，但项目里往往需要统一错误提示、字符计数和清除按钮：

// AppTextField.kt
@Composable
fun AppTextField(
    value: String,
    onValueChange: (String) -> Unit,
    label: String,
    modifier: Modifier = Modifier,
    placeholder: String = "",
    error: String? = null,
    maxLength: Int = Int.MAX_VALUE,
    showCount: Boolean = false,
    clearable: Boolean = false,
    keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
    keyboardActions: KeyboardActions = KeyboardActions.Default
) {
    Column(modifier = modifier) {
        OutlinedTextField(
            value = value,
            onValueChange = { if (it.length  Icon(
                        Icons.Default.Error,
                        contentDescription = "错误",
                        tint = MaterialTheme.colorScheme.error
                    )
                    clearable && value.isNotEmpty() -> IconButton(onClick = { onValueChange("") }) {
                        Icon(Icons.Default.Clear, contentDescription = "清除")
                    }
                    showCount -> Text(
                        text = "${value.length}/$maxLength",
                        style = MaterialTheme.typography.labelSmall,
                        color = if (value.length >= maxLength)
                            MaterialTheme.colorScheme.error
                        else
                            MaterialTheme.colorScheme.onSurfaceVariant
                    )
                }
            },
            keyboardOptions = keyboardOptions,
            keyboardActions = keyboardActions,
            modifier = Modifier.fillMaxWidth()
        )

        // 错误信息行
        AnimatedVisibility(visible = error != null) {
            Text(
                text = error ?: "",
                color = MaterialTheme.colorScheme.error,
                style = MaterialTheme.typography.labelMedium,
                modifier = Modifier.padding(start = 16.dp, top = 4.dp)
            )
        }
    }
}

焦点链管理（多个输入框按回车切换焦点）：

@Composable
fun LoginForm() {
    val focusManager = LocalFocusManager.current
    var username by remember { mutableStateOf("") }
    var password by remember { mutableStateOf("") }

    AppTextField(
        value = username,
        onValueChange = { username = it },
        label = "用户名",
        keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
        keyboardActions = KeyboardActions(
            onNext = { focusManager.moveFocus(FocusDirection.Down) }
        )
    )

    AppTextField(
        value = password,
        onValueChange = { password = it },
        label = "密码",
        keyboardOptions = KeyboardOptions(
            keyboardType = KeyboardType.Password,
            imeAction = ImeAction.Done
        ),
        keyboardActions = KeyboardActions(
            onDone = { focusManager.clearFocus() }
        )
    )
}

五、动画组件——让 UI 更有生命力

Compose 动画 API 非常强大，但很多开发者只停留在 AnimatedVisibility。这里介绍几个实用的动画模式：

1. 骨架屏（Shimmer 效果）

@Composable
fun ShimmerEffect(
    modifier: Modifier = Modifier,
    widthOfShadowBrush: Int = 500,
    angleOfAxisY: Float = 270f,
    durationMillis: Int = 1000
) {
    val shimmerColors = listOf(
        Color.White.copy(alpha = 0.3f),
        Color.White.copy(alpha = 0.5f),
        Color.White.copy(alpha = 1.0f),
        Color.White.copy(alpha = 0.5f),
        Color.White.copy(alpha = 0.3f),
    )

    val transition = rememberInfiniteTransition(label = "shimmer")
    val translateAnimation = transition.animateFloat(
        initialValue = 0f,
        targetValue = (durationMillis + widthOfShadowBrush).toFloat(),
        animationSpec = infiniteRepeatable(
            animation = tween(durationMillis = durationMillis, easing = LinearEasing),
            repeatMode = RepeatMode.Restart,
        ),
        label = "shimmer_translate"
    )

    val brush = Brush.linearGradient(
        colors = shimmerColors,
        start = Offset(x = translateAnimation.value - widthOfShadowBrush, y = 0.0f),
        end = Offset(x = translateAnimation.value, y = angleOfAxisY),
    )

    Box(modifier = modifier.background(brush))
}

// 使用方式
@Composable
fun UserCardSkeleton() {
    Row(modifier = Modifier.padding(16.dp)) {
        ShimmerEffect(
            modifier = Modifier.size(48.dp).clip(CircleShape)
        )
        Spacer(modifier = Modifier.width(12.dp))
        Column(verticalArrangement = Arrangement.spacedBy(8.dp)) {
            ShimmerEffect(modifier = Modifier.width(120.dp).height(16.dp).clip(RoundedCornerShape(4.dp)))
            ShimmerEffect(modifier = Modifier.width(80.dp).height(12.dp).clip(RoundedCornerShape(4.dp)))
        }
    }
}

2. 展开/收起动画

@Composable
fun ExpandableCard(
    title: String,
    content: @Composable () -> Unit
) {
    var expanded by remember { mutableStateOf(false) }
    val rotationAngle by animateFloatAsState(
        targetValue = if (expanded) 180f else 0f,
        animationSpec = tween(durationMillis = 300),
        label = "arrow_rotation"
    )

    Card(
        onClick = { expanded = !expanded },
        modifier = Modifier.fillMaxWidth()
    ) {
        Column(modifier = Modifier.padding(16.dp)) {
            Row(
                modifier = Modifier.fillMaxWidth(),
                horizontalArrangement = Arrangement.SpaceBetween,
                verticalAlignment = Alignment.CenterVertically
            ) {
                Text(text = title, style = MaterialTheme.typography.titleMedium)
                Icon(
                    Icons.Default.ExpandMore,
                    contentDescription = null,
                    modifier = Modifier.rotate(rotationAngle)
                )
            }
            AnimatedVisibility(
                visible = expanded,
                enter = expandVertically() + fadeIn(),
                exit = shrinkVertically() + fadeOut()
            ) {
                Box(modifier = Modifier.padding(top = 8.dp)) {
                    content()
                }
            }
        }
    }
}

六、LazyColumn 性能优化——避免常见陷阱

Compose 列表是性能问题的重灾区。这里总结最关键的几个优化点：

1. 始终为列表项指定 key

// ❌ 错误：不指定 key，滚动时 item 会被错误复用
LazyColumn {
    items(userList) { user ->
        UserCard(user = user)
    }
}

// ✅ 正确：指定稳定的 key
LazyColumn {
    items(
        items = userList,
        key = { user -> user.id }
    ) { user ->
        UserCard(user = user)
    }
}

2. 避免在 items 中创建 Lambda

// ❌ 每次重组都会创建新的 Lambda 对象
LazyColumn {
    items(userList, key = { it.id }) { user ->
        UserCard(
            user = user,
            onClick = { viewModel.onUserClick(user.id) }  // 每次重组都是新对象
        )
    }
}

// ✅ 将回调提升或用 remember 缓存
@Stable
data class UserActions(
    val onUserClick: (String) -> Unit,
)

LazyColumn {
    items(userList, key = { it.id }) { user ->
        UserCard(user = user, actions = actions)
    }
}

3. 使用 derivedStateOf 优化滚动状态监听

// ❌ listState.firstVisibleItemIndex 变化时会触发不必要的重组
val showScrollTop = listState.firstVisibleItemIndex > 0

// ✅ 只有布尔值变化时才触发重组
val showScrollTop by remember {
    derivedStateOf { listState.firstVisibleItemIndex > 0 }
}

踩坑：图片加载导致的列表抖动：在加载网络图片时，如果没有指定尺寸，图片加载完成后高度变化会导致列表跳动。解决方案是始终为图片指定固定高度或宽高比：

AsyncImage(
    model = imageUrl,
    contentDescription = null,
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .fillMaxWidth()
        .aspectRatio(16f / 9f)  // 固定宽高比，避免加载前后高度变化
)

七、Preview 管理——提升团队开发效率

一个良好的 Preview 体系能大幅提升 UI 开发效率，减少真机调试次数：

// ComponentPreview.kt —— 统一 Preview 配置
@Preview(name = "Light Mode", showBackground = true)
@Preview(name = "Dark Mode", showBackground = true, uiMode = Configuration.UI_MODE_NIGHT_YES)
@Preview(name = "Large Font", showBackground = true, fontScale = 1.5f)
annotation class MultiPreview

// 在组件文件中使用
@MultiPreview
@Composable
private fun AppButtonPreview() {
    AppTheme {
        Column(
            modifier = Modifier.padding(16.dp),
            verticalArrangement = Arrangement.spacedBy(8.dp)
        ) {
            AppButton(text = "Primary Button", onClick = {})
            AppButton(text = "Loading...", onClick = {}, loading = true)
            AppButton(text = "Disabled", onClick = {}, enabled = false)
            AppButton(text = "Danger", onClick = {}, buttonType = ButtonType.Danger)
        }
    }
}

通过自定义 @MultiPreview 注解，一次写 Preview 就能同时看到亮色/暗色/大字体效果，无需重复标注。

八、总结与最佳实践清单

经过以上几个核心模块的封装实践，整理出以下最佳实践清单，建议在团队内制定为规范：

✅ 所有颜色、字体、间距通过 Theme 系统管理，禁止硬编码
✅ 组件参数设计遵循"最小必要原则"，复杂样式通过 Modifier 扩展传入
✅ 有副作用的 UI 状态（loading、error）统一作为参数传入，不在组件内部管理
✅ LazyColumn/LazyRow 中的 item 必须指定稳定的 key
✅ 监听滚动、键盘等高频状态时使用 derivedStateOf
✅ 网络图片必须指定固定尺寸或宽高比
✅ 每个公共组件必须有覆盖亮暗模式的 Preview
✅ 动画使用 AnimatedContent/AnimatedVisibility 而非手动控制透明度

Compose 组件库的建设是一个持续演进的过程。建议从最高频的按钮、输入框、卡片开始封装，在实际项目使用中不断打磨，逐步沉淀出真正适合团队的组件体系。

完整代码已整理为模板项目，有需要的同学欢迎在评论区留言交流。

Android Hilt 依赖注入实战：从零搭建 Clean Architecture 注入体系

Fri, 27 Mar 2026 08:06:49 +0800

\n\n

\u4e3a\u4ec0\u4e48\u8981\u5728 Android \u9879\u76ee\u4e2d\u5f15\u5165 Hilt\uff1f

\u4f9d\u8d56\u6ce8\u5165\uff08Dependency Injection\uff0cDI\uff09\u662f\u73b0\u4ee3 Android \u5f00\u53d1\u4e2d\u51e0\u4e4e\u65e0\u6cd5\u7ed5\u5f00\u7684\u8bdd\u9898\u3002\u624b\u52a8\u7ba1\u7406\u5bf9\u8c61\u4f9d\u8d56\u4e0d\u4ec5\u7e41\u7410\uff0c\u8fd8\u5bb9\u6613\u5728 Activity/Fragment \u751f\u547d\u5468\u671f\u4e2d\u5f15\u53d1\u5185\u5b58\u6cc4\u6f0f\u3002Google \u5b98\u65b9\u63a8\u8350\u7684 Hilt \u6846\u67b6\u57fa\u4e8e Dagger2\uff0c\u901a\u8fc7\u7f16\u8bd1\u671f\u4ee3\u7801\u751f\u6210\uff0c\u5728\u4fdd\u6301\u9ad8\u6027\u80fd\u7684\u540c\u65f6\u5927\u5e45\u964d\u4f4e\u4e86\u4e0a\u624b\u95e8\u69db\u3002

\u672c\u6587\u4ee5\u4e00\u4e2a\u771f\u5b9e\u7684\u201c\u7528\u6237\u767b\u5f55 + \u6570\u636e\u52a0\u8f7d\u201d\u529f\u80fd\u4e3a\u7ebf\u7d22\uff0c\u5e26\u4f60\u4ece\u96f6\u641e\u5efa\u4e00\u5957\u7b26\u5408 Clean Architecture \u7684 Hilt \u6ce8\u5165\u4f53\u7cfb\uff0c\u8986\u76d6\u4ee5\u4e0b\u573a\u666f\uff1a

\n
ViewModel \u4e2d\u6ce8\u5165 Repository
\n
Repository \u4e2d\u6ce8\u5165 Retrofit \u548c Room
\n
\u591a\u6a21\u5757\u9879\u76ee\u4e2d\u7684\u8de8\u6a21\u5757\u6ce8\u5165
\n
\u5355\u5143\u6d4b\u8bd5\u4e2d\u66ff\u6362\u771f\u5b9e\u4f9d\u8d56
\n

\n\n

\u7b2c\u4e00\u6b65\uff1a\u6dfb\u52a0\u4f9d\u8d56\u4e0e\u57fa\u7840\u914d\u7f6e

\u5728\u9879\u76ee\u6839\u76ee\u5f55 build.gradle \u4e2d\u6dfb\u52a0 Hilt \u63d2\u4ef6\uff1a

// \u6839\u76ee\u5f55 build.gradle\nplugins {\n    id \'com.google.dagger.hilt.android\' version \'2.51.1\' apply false\n}\n

\u5728 app \u6a21\u5757 build.gradle \u4e2d\uff1a

plugins {\n    id \'com.google.dagger.hilt.android\'\n    id \'kotlin-kapt\'\n}\n\ndependencies {\n    implementation "com.google.dagger:hilt-android:2.51.1"\n    kapt "com.google.dagger:hilt-android-compiler:2.51.1"\n    implementation "androidx.hilt:hilt-navigation-compose:1.2.0"\n}\n

\u63a5\u7740\u7ed9 Application \u7c7b\u52a0\u4e0a @HiltAndroidApp \u6ce8\u89e3\uff0c\u8fd9\u662f Hilt \u7684\u5165\u53e3\uff0c\u4e0d\u80fd\u7701\u7565\uff1a

@HiltAndroidApp\nclass MyApp : Application()\n

\u522b\u5fd8\u4e86\u5728 AndroidManifest.xml \u4e2d\u6307\u5b9a android:name=".MyApp"\u3002

\n\n

\u7b2c\u4e8c\u6b65\uff1a\u6784\u5efa Network \u548c Database \u6a21\u5757

Hilt \u901a\u8fc7 @Module + @InstallIn \u6765\u58f0\u660e\u5982\u4f55\u63d0\u4f9b\u4f9d\u8d56\u3002\u7f51\u7edc\u5c42\u548c\u6570\u636e\u5e93\u5c42\u901a\u5e38\u4f5c\u7528\u57df\u4e3a\u6574\u4e2a\u5e94\u7528\u751f\u547d\u5468\u671f\uff0c\u4f7f\u7528 SingletonComponent\uff1a

@Module\n@InstallIn(SingletonComponent::class)\nobject NetworkModule {\n\n    @Provides\n    @Singleton\n    fun provideOkHttpClient(): OkHttpClient {\n        return OkHttpClient.Builder()\n            .addInterceptor(HttpLoggingInterceptor().apply {\n                level = HttpLoggingInterceptor.Level.BODY\n            })\n            .connectTimeout(30, TimeUnit.SECONDS)\n            .build()\n    }\n\n    @Provides\n    @Singleton\n    fun provideRetrofit(okHttpClient: OkHttpClient): Retrofit {\n        return Retrofit.Builder()\n            .baseUrl("https://api.example.com/")\n            .client(okHttpClient)\n            .addConverterFactory(GsonConverterFactory.create())\n            .build()\n    }\n\n    @Provides\n    @Singleton\n    fun provideUserApi(retrofit: Retrofit): UserApi {\n        return retrofit.create(UserApi::class.java)\n    }\n}\n

\u6570\u636e\u5e93\u6a21\u5757\u540c\u7406\uff1a

@Module\n@InstallIn(SingletonComponent::class)\nobject DatabaseModule {\n\n    @Provides\n    @Singleton\n    fun provideDatabase(@ApplicationContext context: Context): AppDatabase {\n        return Room.databaseBuilder(\n            context,\n            AppDatabase::class.java,\n            "app_database"\n        ).build()\n    }\n\n    @Provides\n    fun provideUserDao(database: AppDatabase): UserDao {\n        return database.userDao()\n    }\n}\n

\u8e29\u5751\u63d0\u793a\uff1aUserDao \u4e0d\u52a0 @Singleton\uff0c\u56e0\u4e3a Room \u4f1a\u81ea\u5df1\u7ba1\u7406 DAO \u7684\u751f\u547d\u5468\u671f\uff0c\u91cd\u590d\u5305\u88c5\u53cd\u800c\u53ef\u80fd\u5f15\u53d1\u95ee\u9898\u3002

\n\n

\u7b2c\u4e09\u6b65\uff1a\u6ce8\u5165 Repository \u548c ViewModel

Repository \u5c42\u8d1f\u8d23\u6574\u5408\u7f51\u7edc\u548c\u672c\u5730\u6570\u636e\u6e90\uff0c\u4f7f\u7528\u6784\u9020\u51fd\u6570\u6ce8\u5165\uff1a

class UserRepository @Inject constructor(\n    private val userApi: UserApi,\n    private val userDao: UserDao\n) {\n    suspend fun login(username: String, password: String): Result<User> {\n        return try {\n            val user = userApi.login(LoginRequest(username, password))\n            userDao.insertUser(user)\n            Result.success(user)\n        } catch (e: Exception) {\n            Result.failure(e)\n        }\n    }\n\n    fun getCachedUser(): Flow<User?> = userDao.getUser()\n}\n

ViewModel \u4e2d\u4f7f\u7528 @HiltViewModel + @Inject constructor\uff0c\u65e0\u9700\u624b\u52a8\u521b\u5efa ViewModelFactory\uff1a

@HiltViewModel\nclass LoginViewModel @Inject constructor(\n    private val userRepository: UserRepository\n) : ViewModel() {\n\n    private val _loginState = MutableStateFlow<LoginState>(LoginState.Idle)\n    val loginState: StateFlow<LoginState> = _loginState.asStateFlow()\n\n    fun login(username: String, password: String) {\n        viewModelScope.launch {\n            _loginState.value = LoginState.Loading\n            val result = userRepository.login(username, password)\n            _loginState.value = if (result.isSuccess) {\n                LoginState.Success(result.getOrNull()!!)\n            } else {\n                LoginState.Error(result.exceptionOrNull()?.message ?: "\u767b\u5f55\u5931\u8d25")\n            }\n        }\n    }\n}\n

\u5728 Activity/Fragment \u4e2d\u83b7\u53d6 ViewModel \u53ea\u9700\uff1a

@AndroidEntryPoint\nclass LoginActivity : AppCompatActivity() {\n    private val viewModel: LoginViewModel by viewModels()\n}\n

\u6ce8\u610f Activity \u5fc5\u987b\u52a0 @AndroidEntryPoint\uff0c\u5426\u5219 Hilt \u65e0\u6cd5\u6ce8\u5165\u3002

\n\n

\u7b2c\u56db\u6b65\uff1a\u5355\u5143\u6d4b\u8bd5\u4e2d\u66ff\u6362\u4f9d\u8d56

Hilt \u5bf9\u6d4b\u8bd5\u7684\u652f\u6301\u975e\u5e38\u5b8c\u5584\uff0c\u901a\u8fc7 @TestInstallIn \u53ef\u4ee5\u66ff\u6362\u6b63\u5f0f\u6a21\u5757\uff1a

@TestInstallIn(\n    components = [SingletonComponent::class],\n    replaces = [NetworkModule::class]\n)\n@Module\nobject FakeNetworkModule {\n\n    @Provides\n    @Singleton\n    fun provideUserApi(): UserApi = FakeUserApi()\n}\n

\u6d4b\u8bd5\u7c7b\uff1a

@HiltAndroidTest\nclass LoginViewModelTest {\n\n    @get:Rule\n    var hiltRule = HiltAndroidRule(this)\n\n    @Inject\n    lateinit var userRepository: UserRepository\n\n    @Before\n    fun init() {\n        hiltRule.inject()\n    }\n\n    @Test\n    fun testLoginSuccess() = runTest {\n        val viewModel = LoginViewModel(userRepository)\n        viewModel.login("test_user", "password123")\n        assertTrue(viewModel.loginState.value is LoginState.Success)\n    }\n}\n

\n\n

\u5e38\u89c1\u95ee\u9898\u4e0e\u6700\u4f73\u5b9e\u8df5

\n
\u4f5c\u7528\u57df\u9009\u62e9\uff1aActivity \u5185\u7684\u4f9d\u8d56\u7528 ActivityComponent\uff0c\u907f\u514d Singleton \u6301\u6709 Activity \u5f15\u7528\u9020\u6210\u6cc4\u6f0f
\n
@Qualifier \u533a\u5206\u540c\u7c7b\u578b\uff1a\u82e5\u6709\u591a\u4e2a OkHttpClient\uff0c\u7528 @Named \u6216\u81ea\u5b9a\u4e49 Qualifier \u533a\u5206
\n
\u61d2\u52a0\u8f7d\uff1a\u7528 Lazy \u5305\u88c5\u4e0d\u9700\u8981\u7acb\u5373\u521d\u59cb\u5316\u7684\u4f9d\u8d56\uff0c\u51cf\u5c11\u542f\u52a8\u8017\u65f6
\n
\u591a\u6a21\u5757\u9879\u76ee\uff1a\u6bcf\u4e2a feature \u6a21\u5757\u53ef\u4ee5\u6709\u81ea\u5df1\u7684 @InstallIn(ActivityComponent::class) \u6a21\u5757\uff0cHilt \u4f1a\u81ea\u52a8\u5408\u5e76
\n
kapt \u7f16\u8bd1\u6162\uff1f\u5347\u7ea7\u5230 KSP \u53ef\u4ee5\u663e\u8457\u63d0\u5347\u7f16\u8bd1\u901f\u5ea6\uff0cHilt \u5df2\u652f\u6301 KSP
\n

\u638c\u63e1\u8fd9\u5957\u6a21\u5f0f\u540e\uff0c\u4f60\u4f1a\u53d1\u73b0\u4ee3\u7801\u53ef\u6d4b\u8bd5\u6027\u3001\u53ef\u7ef4\u62a4\u6027\u90fd\u6709\u8d28\u7684\u63d0\u5347\u3002\u4f9d\u8d56\u6ce8\u5165\u4e0d\u53ea\u662f\u6846\u67b6\u7684\u4f7f\u7528\uff0c\u66f4\u662f\u4e00\u79cd\u9762\u5411\u63a5\u53e3\u7f16\u7a0b\u7684\u601d\u7ef4\u65b9\u5f0f\u3002

PHP 8.3 新特性实战：类型系统增强与性能优化完全指南

Thu, 26 Mar 2026 08:07:30 +0800

为什么要升级到 PHP 8.3？

PHP 8.3 于 2023 年 11 月正式发布，带来了一系列令开发者兴奋的新特性。这不只是一次小版本更新，它在类型系统、性能和内置函数层面都做了有意义的改进。如果你还在用 PHP 7.x 或 PHP 8.0/8.1，现在是一个绝佳的升级时机。

本文将通过真实代码示例，逐一讲解 PHP 8.3 最值得关注的新特性，并附上升级过程中常见的踩坑点，让你看完就能动手实践。

特性一：类型化类常量（Typed Class Constants）

在 PHP 8.3 之前，类常量没有类型声明，这导致继承时可能出现类型不一致的隐患。PHP 8.3 引入了类型化常量，让代码更加健壮。

<?php
// PHP 8.3 之前——无类型约束
class Config {
    const VERSION = '1.0.0';
}

// PHP 8.3——可以声明常量类型
class Config {
    const string VERSION = '1.0.0';
    const int MAX_RETRY = 3;
    const float TIMEOUT = 30.0;
    const array ALLOWED_METHODS = ['GET', 'POST'];
}

// 继承时类型必须兼容，否则报错
class ChildConfig extends Config {
    // 以下会抛出 TypeError
    // const string VERSION = 123;  // ❌ 类型不符
    const string VERSION = '2.0.0'; // ✅ 正确
}

踩坑记录：如果你在枚举（enum）中使用类型化常量，需注意枚举常量的类型必须与枚举的 backed type 兼容，否则在运行时会报错。

特性二：json_validate() 函数——终于不用 json_decode 了

过去我们要验证一个字符串是否为合法 JSON，只能先 json_decode 再判断 json_last_error()，既浪费内存又不直观。PHP 8.3 直接提供了 json_validate() 函数。

<?php
// PHP 8.2 及以前的写法
function isValidJson(string $json): bool {
    json_decode($json);
    return json_last_error() === JSON_ERROR_NONE;
}

// PHP 8.3 新写法——更高效，不需要解析整个 JSON
$validJson = '{"name": "Alice", "age": 30}';
$invalidJson = '{name: "Alice"}';

var_dump(json_validate($validJson));   // bool(true)
var_dump(json_validate($invalidJson)); // bool(false)

// 还支持设置最大嵌套深度
var_dump(json_validate('{"a":{"b":{"c":1}}}', depth: 2)); // bool(false)，超过深度限制

这个函数在 API 数据接收、消息队列消费场景中非常实用，性能比原来的方式提升了约 15%～20%，因为它不需要在内存中构建 PHP 数组。

特性三：Readonly 属性增强

PHP 8.1 引入了 readonly 属性，但有一个痛点：无法在克隆对象时修改 readonly 属性。PHP 8.3 对此做出了改进，允许在 __clone 方法中对 readonly 属性重新赋值。

<?php
class User {
    public function __construct(
        public readonly int $id,
        public readonly string $name,
        public readonly string $email,
    ) {}

    // PHP 8.3：可以在 __clone 中修改 readonly 属性
    public function withEmail(string $newEmail): static {
        $clone = clone $this;
        $clone->email = $newEmail; // ✅ PHP 8.3 允许，8.2 会报错
        return $clone;
    }
}

$user = new User(1, 'Alice', 'alice@example.com');
$updatedUser = $user->withEmail('newalice@example.com');

echo $user->email;        // alice@example.com（原对象不变）
echo $updatedUser->email; // newalice@example.com

这个特性配合不可变对象（Immutable Object）模式非常好用，适合用在 DDD（领域驱动设计）的值对象中，实现真正的"不可变但可派生"的设计。

特性四：新的随机数 API——Randomizer 增强

PHP 8.2 引入了 Random\Randomizer 类，PHP 8.3 在此基础上增加了两个实用方法：getBytesFromString() 和 getFloat()。

<?php
use Random\Randomizer;

$randomizer = new Randomizer();

// 从指定字符集中随机取 N 个字节——非常适合生成验证码
$captcha = $randomizer->getBytesFromString('ABCDEFGHJKLMNPQRSTUVWXYZ23456789', 6);
echo $captcha; // 例如：K7MN3P

// 生成指定范围内的随机浮点数
$price = $randomizer->getFloat(9.99, 99.99);
echo round($price, 2); // 例如：42.57

// 配合 InteractWithSeed 引擎，可以生成可重现的随机数（测试场景）
$seeded = new Randomizer(new Random\Engine\Xoshiro256StarStar(42));
echo $seeded->getBytesFromString('0123456789', 8); // 每次固定输出相同结果

实战场景：生成优惠码、邀请码时，用 getBytesFromString 代替 substr(str_shuffle(...))，既安全又简洁，还避免了字符分布不均的问题。

升级到 PHP 8.3 的踩坑总结

在实际项目升级过程中，笔者遇到了以下几个常见问题，整理如下供参考：

旧版 Composer 包兼容问题：升级前用 composer outdated 检查依赖，部分老旧扩展（如 carbon/carbon < 2.72）需要同步升级。
已弃用特性报错：mb_strtolower 等函数的部分用法在 PHP 8.3 中被标记为 deprecated，要留意 error_log 中的 deprecation warning。
类型声明更严格：PHP 8.3 对动态属性访问更加严格，未声明的动态属性赋值会产生 deprecated 警告，建议添加 #[AllowDynamicProperties] 注解或重构代码。
Docker 镜像更新：推荐使用 php:8.3-fpm-alpine 镜像，体积小、版本新，配合 OPcache 开箱即用性能表现优秀。

# Dockerfile 示例
FROM php:8.3-fpm-alpine

# 安装常用扩展
RUN docker-php-ext-install pdo pdo_mysql opcache

# OPcache 配置
RUN echo "opcache.enable=1" >> /usr/local/etc/php/conf.d/opcache.ini \
    && echo "opcache.jit_buffer_size=128M" >> /usr/local/etc/php/conf.d/opcache.ini \
    && echo "opcache.jit=1255" >> /usr/local/etc/php/conf.d/opcache.ini

总结

PHP 8.3 的新特性虽然看起来都不大，但每一项都解决了实际开发中的真实痛点：类型化常量让继承更安全，json_validate 让 JSON 校验更高效，readonly 克隆增强让不可变对象设计更优雅，新的随机数 API 让安全随机数生成更简单。

建议先在测试环境中运行 php -l 语法检查和单元测试，逐步验证兼容性，再推进到生产环境。如果你的项目已经在 PHP 8.1/8.2 上运行，升级到 8.3 的成本是非常低的，性能收益却立竿见影。