Resmic's | BLOG

PHP 8.3 新特性实战指南：类型化常量、json_validate 与平滑升级

Sun, 26 Apr 2026 08:10:13 +0800

一、为什么升级到 PHP 8.3？

PHP 8.3 于 2023 年 11 月正式发布，是 PHP 8.x 系列的最新稳定版本。相比 PHP 8.2，它在类型系统、性能优化和开发体验上都有显著提升。如果你还在使用 PHP 7.x 或 PHP 8.0/8.1，现在是迁移到 8.3 的绝佳时机。

以下是升级 PHP 8.3 的主要理由：

类型化类常量，让代码更严格、更可维护
内置 json_validate()，无需再自己封装验证逻辑
新的 #[Override] 属性，防止方法覆盖错误
动态类常量获取，支持更灵活的常量访问方式
性能比 PHP 7.4 提升约 40%，比 PHP 8.0 提升约 15%

二、类型化类常量（Typed Class Constants）

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.5;
    const array ALLOWED_METHODS = ['GET', 'POST', 'PUT', 'DELETE'];
}

// 子类试图用错误类型覆盖将报错
class DevConfig extends Config {
    const string VERSION = '1.0.0-dev'; // ✅ 正确
    // const int VERSION = 1; // ❌ 报错：类型不兼容
}

类型化常量支持所有标量类型（int、float、string、bool）、array、以及类/接口类型，还支持 nullable 语法（如 ?string）。

三、json_validate() 函数

在 PHP 8.3 之前，验证一个字符串是否为合法 JSON 通常需要这样做：

<?php
// 旧方式：解码后检查错误（性能差，会分配内存）
function isValidJson(string $json): bool {
    json_decode($json);
    return json_last_error() === JSON_ERROR_NONE;
}

PHP 8.3 引入了原生的 json_validate()，它只做语法校验，不分配解码内存，性能更好：

<?php
// PHP 8.3 新方式：高效验证
$data = '{"name": "Alice", "age": 30}';

if (json_validate($data)) {
    echo "合法的 JSON";
    $obj = json_decode($data); // 只在需要时再解码
}

// 验证嵌套深度
if (json_validate($data, depth: 5)) {
    // 限制最大嵌套层数为 5
}

// 使用标志位
if (json_validate($data, flags: JSON_INVALID_UTF8_IGNORE)) {
    // 忽略无效 UTF-8 字符
}

在需要大量验证 JSON 字符串合法性的场景（如 API 网关、消息队列消费者），这个函数可以显著降低内存开销。

四、#[Override] 属性

#[Override] 是 PHP 8.3 引入的新属性，用于标记一个方法是对父类方法的覆盖。如果父类中不存在同名方法，PHP 将抛出编译错误，有效防止因拼写错误导致的"静默失效"问题。

<?php
class Logger {
    public function log(string $message): void {
        echo $message . PHP_EOL;
    }
}

class FileLogger extends Logger {
    #[Override]
    public function log(string $message): void {
        // 确保这里真的覆盖了父类方法
        file_put_contents('/var/log/app.log', $message . PHP_EOL, FILE_APPEND);
    }
    
    // #[Override]
    // public function logg(string $message): void { // ❌ 报错：父类无此方法
    //     ...
    // }
}

这在大型项目和团队协作中特别有价值，可以在 code review 阶段之前就发现覆盖错误。

五、实战：平滑升级现有 PHP 项目

升级到 PHP 8.3 前，建议按以下步骤操作：

第一步：在本地或测试环境安装 PHP 8.3，使用 php -v 确认版本
第二步：运行 composer update，检查依赖包兼容性，关注废弃（deprecated）警告
第三步：使用 Rector 自动化重构工具，自动升级代码语法
第四步：运行完整测试套件，修复失败的测试用例
第五步：分阶段灰度上线，监控错误日志

# 使用 Rector 自动升级代码
composer require rector/rector --dev

# 创建 rector.php 配置
cat > rector.php << 'RECTOR_EOF'
<?php
use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
    ->withSets([LevelSetList::UP_TO_PHP_83]);
RECTOR_EOF

# 预览变更（不实际修改）
./vendor/bin/rector process --dry-run

# 应用变更
./vendor/bin/rector process

完成升级后，你的代码将充分利用 PHP 8.3 的所有新特性，同时享受更好的运行时性能。

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

Sat, 25 Apr 2026 08:07:29 +0800

一、PHP 8.3 概览：为什么值得升级？

PHP 8.3 于 2023 年 11 月正式发布，是 PHP 8.x 系列的最新稳定版本。相比 8.2，它在类型安全、只读属性、随机数 API 以及错误处理等方面都有显著改进。

对于追求代码质量与可维护性的现代 PHP 开发者来说，升级到 8.3 能带来以下核心收益：

更严格的类型系统，减少运行时错误
只读属性深度克隆支持，适合复杂值对象场景
新的 json_validate() 函数，提升 JSON 处理效率
随机数扩展 (Random\Randomizer) 功能增强
动态类常量获取更简洁
性能小幅提升，JIT 编译更稳定

本文将结合真实代码示例，逐一深入解析这些变化。

二、只读属性改进：深度克隆支持

PHP 8.1 引入了只读属性 (readonly)，8.2 支持只读类，而 8.3 的重要改进是允许在克隆时重新初始化只读属性，彻底解决了不可变值对象难以拷贝修改的痛点。

<?php

class UserProfile
{
    public function __construct(
        public readonly int    $id,
        public readonly string $name,
        public readonly string $email,
    ) {}

    public function withEmail(string $newEmail): static
    {
        $clone = clone $this;
        // PHP 8.3: 克隆后可重新赋值 readonly 属性
        $clone->email = $newEmail;
        return $clone;
    }
}

$user = new UserProfile(1, 'Alice', 'alice@example.com');
$updated = $user->withEmail('alice@new.com');

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

这一特性让"不可变对象 + 修改返回新实例"的 DDD 值对象模式在 PHP 中变得真正实用。

三、类型系统增强：动态类常量与枚举改进

PHP 8.3 允许使用动态表达式访问类常量和枚举成员，语法更灵活，减少了过去必须用 constant() 函数的尴尬写法。

<?php

class Status
{
    const ACTIVE  = 'active';
    const BLOCKED = 'blocked';
    const PENDING = 'pending';
}

// PHP 8.3 新写法：动态常量访问
$key = 'ACTIVE';
echo Status::{$key}; // active

// 枚举同样支持
enum Color: string
{
    case Red   = 'red';
    case Green = 'green';
    case Blue  = 'blue';
}

$colorName = 'Red';
$color = Color::{$colorName};
echo $color->value; // red

此外，PHP 8.3 为枚举增加了 getConstant() 方法，与类常量保持接口一致，方便反射场景使用。

<?php

$reflection = new ReflectionEnum(Color::class);
$case = $reflection->getCase('Green');
echo $case->getValue()->value; // green

四、新增 json_validate() 函数

在 PHP 8.3 之前，验证一个字符串是否为合法 JSON 只能先 json_decode() 再检查 json_last_error()，这不仅繁琐，而且会创建不必要的内存对象。PHP 8.3 引入了专用的 json_validate()，仅做语法验证，不解析内容。

<?php

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

// PHP 8.3 新写法
$validJson   = '{"name":"Alice","age":30}';
$invalidJson = '{name: Alice}';

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

// 支持指定最大嵌套深度
$deepJson = str_repeat('{"a":', 100) . '1' . str_repeat('}', 100);
var_dump(json_validate($deepJson, depth: 50)); // bool(false)

在高并发接口场景中，使用 json_validate() 对大量请求做前置过滤，相比 json_decode() 内存占用显著降低。

五、随机数 API 增强：Randomizer 新方法

PHP 8.2 引入了 Random\Randomizer 类，8.3 在此基础上新增了 getBytesFromString() 和 getFloat()/nextFloat() 方法，让安全随机数生成更加灵活。

<?php

use Random\Randomizer;
use Random\Engine\Secure;

$randomizer = new Randomizer(new Secure());

// 从指定字符集中随机抽取 N 个字符（PHP 8.3 新增）
$charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
$token = $randomizer->getBytesFromString($charset, 32);
echo $token; // 例如：aZ3kQ7mBx...（32位安全随机字符串）

// 生成指定范围内的浮点数（PHP 8.3 新增）
$price = $randomizer->getFloat(1.0, 100.0);
echo round($price, 2); // 例如：47.83

// nextFloat()：生成 [0, 1) 区间的浮点数
$ratio = $randomizer->nextFloat();
echo $ratio; // 例如：0.7341...

这些方法底层使用密码学安全的随机源，适合生成邀请码、临时密码、A/B 测试分流比例等场景，比 rand()/mt_rand() 更安全可靠。

六、类型声明改进：never 返回类型与交集类型

PHP 8.3 完善了 never 返回类型的使用范围，并对交集类型 (A&B) 的兼容性做了增强。以下是几个实用示例：

<?php

// never 返回类型：表示该函数永远不会正常返回
function throwNotFound(string $message): never
{
    throw new RuntimeException($message);
}

// 交集类型：要求参数同时实现多个接口
interface Countable2
{
    public function count(): int;
}

interface Stringable2
{
    public function __toString(): string;
}

function process(Countable2&Stringable2 $value): string
{
    return "Count: {$value->count()}, String: {$value}";
}

// PHP 8.3 新增：#[\Override] 注解
class Base
{
    public function calculate(): int
    {
        return 42;
    }
}

class Child extends Base
{
    #[\Override]
    public function calculate(): int // 若父类不存在此方法，编译期报错
    {
        return parent::calculate() * 2;
    }
}

$c = new Child();
echo $c->calculate(); // 84

#[\Override] 注解是 PHP 8.3 引入的实用安全特性，能在编译期捕获"子类方法名拼写错误导致未真正覆盖父类方法"的低级 bug。

七、实战迁移建议与注意事项

升级到 PHP 8.3 前，需要关注以下不兼容变化：

废弃的动态属性： 继承自 stdClass 以外的类上动态创建未声明属性，8.3 中会产生 E_DEPRECATED 警告，9.0 将报错
正则表达式错误处理： preg_* 函数在某些错误情况下的返回值语义有细微变化，建议增加错误码检查
FFI 变更： 如果项目使用 FFI 扩展，需注意接口变动
Composer 依赖： 升级前运行 composer outdated 确认所有依赖都支持 PHP 8.3

# 检查项目是否兼容 PHP 8.3
composer require --dev phpstan/phpstan
./vendor/bin/phpstan analyse --level=8 src/

# 使用 PHP Compatibility 检查弃用 API
composer require --dev phpcompatibility/php-compatibility
./vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.3 src/

总体而言，PHP 8.3 是一个值得尽快跟进的版本。改进点集中且实用，迁移成本可控，在 Laravel 10/11、Symfony 6/7 等主流框架上均已获得完整支持。

PHP 8.3 新特性全解析：类型化常量、json_validate与随机性API实战

Fri, 24 Apr 2026 08:09:50 +0800

PHP 8.3 概览：为何值得升级

PHP 8.3 于 2023 年 11 月正式发布，作为 PHP 8.x 系列的最新版本，它在性能、类型安全和开发体验上都有显著改进。对于仍在使用 PHP 7.x 或 PHP 8.0/8.1 的开发者而言，升级到 8.3 不仅可以享受更强的语言特性，还能获得更好的性能表现。

本文将逐一介绍 PHP 8.3 的核心新特性，并通过实际代码示例帮助你快速理解和应用这些特性。

类型化类常量（Typed Class Constants）

PHP 8.3 最受关注的特性之一是支持对类常量声明类型，这极大地提升了代码的可读性和类型安全性。

在 PHP 8.2 及之前，类常量没有类型声明，容易被子类错误覆盖：

// PHP 8.2 之前：没有类型约束
class Config {
    const VERSION = '1.0.0';  // 可以被子类覆盖为任意类型
}

class BadConfig extends Config {
    const VERSION = 123;  // 错误但不报错
}

PHP 8.3 引入类型化类常量后：

// PHP 8.3：强类型常量
class Config {
    const string VERSION = '1.0.0';
    const int MAX_RETRY = 3;
    const array SUPPORTED_FORMATS = ['json', 'xml', 'csv'];
}

class StrictConfig extends Config {
    const string VERSION = '2.0.0';  // 正确
    // const int VERSION = 2;        // Fatal Error！类型不匹配
}

支持的类型包括：bool、int、float、string、array、null、mixed 以及枚举类型等，极大地减少了因常量类型误用导致的 Bug。

json_validate() — 轻量级 JSON 验证

在 PHP 8.3 之前，验证一个字符串是否为合法 JSON，通常需要先 json_decode() 再检查 json_last_error()，这会消耗额外的内存来解析整个 JSON 树。

// PHP 8.2 之前的做法（低效）
function isValidJson(string $json): bool {
    json_decode($json);
    return json_last_error() === JSON_ERROR_NONE;
}

$bigJson = file_get_contents('large_data.json'); // 可能几十MB
isValidJson($bigJson); // 会把整个JSON解析到内存中

PHP 8.3 新增的 json_validate() 只做语法检查，不构建数据结构，内存占用极低：

// PHP 8.3：高效验证
$json = '{"name": "Alice", "age": 30}';

if (json_validate($json)) {
    echo "有效的 JSON！";
    $data = json_decode($json, true); // 只在需要时才解析
}

// 支持嵌套深度限制
json_validate($json, depth: 5);

// 实际性能对比（大文件场景）
$largeJson = str_repeat('{"key":"value"},', 100000);
$largeJson = '[' . rtrim($largeJson, ',') . ']';

// json_validate() 比 json_decode() 快约 30-50%，内存节省 80%

在处理 Webhook 回调、API 数据校验等高频场景下，这一优化能带来明显的性能提升。

新的随机性 API（Randomizer 增强）

PHP 8.2 引入了 Random\Randomizer 类，8.3 对其进行了重要补充，新增了 getBytesFromString() 和 getFloat()、nextFloat() 方法。

use Random\Randomizer;
use Random\Engine\Secure;

$randomizer = new Randomizer(new Secure());

// getBytesFromString：从指定字符集随机取字节
// 非常适合生成验证码、随机密码
$charset = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
$token = $randomizer->getBytesFromString($charset, 32);
echo $token; // 例如："aZ3Km9xQpR7vBnLw2eTfUdYcHsOjGiVl"

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

// nextFloat：生成 [0, 1) 范围的随机浮点数
$probability = $randomizer->nextFloat();
echo $probability; // 例如：0.7342891

// 对比旧方式：mt_rand() 存在分布不均匀问题
// 新 API 基于 CSPRNG，密码学安全且分布均匀

只读属性（Readonly）的改进

PHP 8.1 引入了 readonly 属性，8.2 支持 readonly class，而 8.3 进一步允许在克隆时修改只读属性（通过 __clone 魔术方法），解决了不可变对象难以克隆修改的痛点。

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 $email): static {
        $clone = clone $this;
        $clone->email = $email; // PHP 8.3 允许！之前会报错
        return $clone;
    }
}

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

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

// 这种模式在 DDD（领域驱动设计）中非常有用
// 可以安全地创建不可变值对象的"修改副本"

这一改进让 PHP 在构建不可变数据结构时更加优雅，与现代架构设计模式（如 CQRS、Event Sourcing）的契合度更高。

升级建议与兼容性注意事项

如果你准备将项目升级到 PHP 8.3，以下几点需要特别注意：

移除的特性：部分 PHP 8.0 中已弃用的函数在 8.3 中正式移除，升级前请运行 composer require --dev phpstan/phpstan 进行静态分析。
扩展兼容性：检查项目依赖的 PHP 扩展是否已支持 8.3，尤其是 xdebug、imagick 等。
框架支持：Laravel 10+ 和 Symfony 6.3+ 均已官方支持 PHP 8.3，可放心升级。
测试覆盖：升级前确保有充分的单元测试覆盖，推荐使用 PHPUnit 10.x。
分阶段迁移：生产环境建议先在预发布环境验证 1-2 周，确认无异常再全量切换。

# 快速检查代码兼容性
composer require --dev phpstan/phpstan rector/rector

# 用 Rector 自动迁移代码到 PHP 8.3 风格
vendor/bin/rector process src --config rector.php

# rector.php 配置示例
use Rector\Set\ValueObject\LevelSetList;
return static function (\Rector\Config\RectorConfig $config): void {
    $config->sets([LevelSetList::UP_TO_PHP_83]);
};

PHP 8.3 是一个值得升级的版本，类型化常量、json_validate() 和增强的随机性 API 都是日常开发中的实用利器。建议在新项目中直接使用 PHP 8.3，老项目也可以制定升级计划，逐步享受这些改进带来的红利。

Jetpack Compose 性能优化实战：7大策略打造流畅Android应用

Thu, 23 Apr 2026 08:06:11 +0800

前言：为什么 Compose 性能优化如此重要

Jetpack Compose 自 1.0 稳定版发布以来，已迅速成为 Android UI 开发的首选框架。与传统 View 系统相比，Compose 提供了声明式 UI、更少的样板代码和更强的可组合性。然而，声明式 UI 的本质决定了它依赖重组（Recomposition）机制来刷新界面，若使用不当，频繁的重组会导致严重的性能问题，出现卡顿、丢帧等用户体验下降的情况。

根据 Google 官方的 Android Vitals 数据，超过 60% 的用户会在遭遇严重卡顿后卸载应用。因此，掌握 Compose 性能优化技术是每个 Android 开发者的必修课。本文将从以下几个核心维度展开讲解，并提供可直接落地的代码示例。

一、深入理解重组机制：避免不必要的重组

重组是 Compose 更新 UI 的方式——当状态发生变化时，Compose 会重新执行受影响的可组合函数。理解重组的触发条件是优化的第一步。

1.1 稳定性（Stability）与智能重组

Compose 编译器会分析每个可组合函数的参数类型是否"稳定"。如果参数是稳定的，Compose 在重组时会跳过未发生变化的组合函数，这称为跳过重组（Skippable Recomposition）。

稳定类型：基本类型（Int、String、Boolean 等）、被 @Stable 或 @Immutable 标注的类、Kotlin 不可变数据类
不稳定类型：包含 var 属性的类、List/Map/Set（需改用 ImmutableList）、Java 类（Compose 无法分析其可变性）

// ❌ 不稳定 - 每次父组合重组都会触发此函数重组
data class User(var name: String, var age: Int)

@Composable
fun UserCard(user: User) { ... }

// ✅ 稳定 - 仅在 user 实际变化时重组
@Immutable
data class User(val name: String, val age: Int)

@Composable
fun UserCard(user: User) { ... }

1.2 使用 Compose 编译器报告分析重组

在 build.gradle.kts 中添加以下配置，生成可组合函数的稳定性报告：

// app/build.gradle.kts
composeOptions {
    kotlinCompilerExtensionVersion = "1.5.x"
}
tasks.withType<KotlinCompile>().configureEach {
    compilerOptions {
        freeCompilerArgs.addAll(
            "-P",
            "plugin:androidx.compose.compiler.plugins.kotlin:reportsDestination=${project.buildDir.absolutePath}/compose_reports"
        )
    }
}

编译后在 build/compose_reports/ 目录下查看 *-composables.txt 文件，标注了每个函数是否为 skippable。

二、状态管理最佳实践：精准控制状态作用域

状态的位置决定了重组的范围。错误的状态提升会导致大量不相关的组合函数被迫重组。

2.1 状态下移（State Hoisting Down）

将状态保持在尽可能低的层级，只有真正需要该状态的组合函数才持有它：

// ❌ 状态定义在顶层，导致整个屏幕重组
@Composable
fun HomeScreen() {
    var searchQuery by remember { mutableStateOf("") }
    // ... 大量其他 UI
    SearchBar(query = searchQuery, onQueryChange = { searchQuery = it })
    ProductList() // 与 searchQuery 无关，但被迫重组
}

// ✅ 状态下移到 SearchBar 内部
@Composable
fun HomeScreen() {
    // ... 大量其他 UI
    SearchBar() // 自管理状态，不影响外部
    ProductList()
}

2.2 使用 derivedStateOf 减少不必要的重组

当一个状态是从另一个状态派生出来，且变化频率不同时，使用 derivedStateOf：

val listState = rememberLazyListState()

// ❌ 每次滚动都会触发重组（即使按钮可见性没变）
val showButton = listState.firstVisibleItemIndex > 0

// ✅ 只有当"是否显示"真正改变时才重组
val showButton by remember {
    derivedStateOf { listState.firstVisibleItemIndex > 0 }
}

2.3 Lambda 引用稳定化

传入可组合函数的 lambda 如果每次都是新对象，会导致重组。使用 rememberUpdatedState 或将 lambda 提升为稳定引用：

// ❌ 每次重组都创建新 lambda
@Composable
fun ParentScreen(viewModel: MyViewModel) {
    ItemList(
        onItemClick = { id -> viewModel.onItemSelected(id) } // 每次都是新对象
    )
}

// ✅ 使用 rememberUpdatedState 或 @Stable 的 ViewModel 方法引用
@Composable
fun ParentScreen(viewModel: MyViewModel) {
    val onItemClick = remember { viewModel::onItemSelected }
    ItemList(onItemClick = onItemClick)
}

三、LazyList 性能优化：让列表飞起来

LazyColumn 和 LazyRow 是 Compose 中最常用也最容易出现性能问题的组件。

3.1 必须提供 key 参数

为 LazyList 的每个 item 提供稳定且唯一的 key，避免列表数据变化时的全量重绘：

LazyColumn {
    items(
        items = products,
        key = { product -> product.id } // ✅ 稳定 key
    ) { product ->
        ProductItem(product = product)
    }
}

3.2 使用 contentType 优化 item 复用

当列表包含多种 item 类型时，指定 contentType 让 Compose 更高效地复用组合：

LazyColumn {
    items(
        items = feedItems,
        key = { it.id },
        contentType = { item ->
            when (item) {
                is FeedItem.Banner -> "banner"
                is FeedItem.Product -> "product"
                is FeedItem.Ad -> "ad"
            }
        }
    ) { item ->
        when (item) {
            is FeedItem.Banner -> BannerItem(item)
            is FeedItem.Product -> ProductItem(item)
            is FeedItem.Ad -> AdItem(item)
        }
    }
}

3.3 避免在 item 内部执行耗时操作

图片加载使用 Coil 或 Glide for Compose，异步加载避免阻塞主线程
复杂计算使用 remember 缓存结果
使用 Modifier.animateItem()（Compose 1.7+）替代旧版 animateItemPlacement

@Composable
fun ProductItem(product: Product) {
    // ✅ 缓存格式化结果，避免每次重组都计算
    val formattedPrice = remember(product.price) {
        NumberFormat.getCurrencyInstance().format(product.price)
    }
    
    AsyncImage(
        model = product.imageUrl,
        contentDescription = product.name,
        modifier = Modifier
            .fillMaxWidth()
            .height(200.dp)
    )
    Text(text = formattedPrice)
}

四、动画性能优化：流畅不卡顿

Compose 动画在处理不当时极易造成过度重组，尤其是涉及大量 UI 元素同时动画的场景。

4.1 优先使用 Modifier 动画而非 State 动画

基于 Modifier 的动画（如 graphicsLayer）运行在渲染层，不触发重组；而基于 State 的动画每帧都会触发重组：

// ❌ 基于 State 的动画 - 每帧触发重组
var scale by remember { mutableStateOf(1f) }
val animatedScale by animateFloatAsState(scale)
Box(Modifier.scale(animatedScale)) { ... }

// ✅ 使用 graphicsLayer - 运行在渲染层，零重组
val infiniteTransition = rememberInfiniteTransition()
val scale by infiniteTransition.animateFloat(
    initialValue = 1f,
    targetValue = 1.2f,
    animationSpec = infiniteRepeatable(tween(1000))
)
Box(Modifier.graphicsLayer { scaleX = scale; scaleY = scale }) { ... }

4.2 合理使用 AnimatedVisibility 和 AnimatedContent

// 使用 AnimatedVisibility 时指定 enter/exit 动画避免默认的昂贵动画
AnimatedVisibility(
    visible = isVisible,
    enter = fadeIn(animationSpec = tween(200)),
    exit = fadeOut(animationSpec = tween(200))
) {
    HeavyContent()
}

五、图片与资源加载优化

图片加载是 Android 应用中最常见的性能瓶颈之一，在 Compose 中更需要特别注意。

5.1 Coil 3 最佳配置

// Application 中配置全局 ImageLoader
val imageLoader = ImageLoader.Builder(context)
    .memoryCache {
        MemoryCache.Builder(context)
            .maxSizePercent(0.25) // 使用 25% 内存
            .build()
    }
    .diskCache {
        DiskCache.Builder()
            .directory(context.cacheDir.resolve("image_cache"))
            .maxSizePercent(0.02) // 2% 磁盘空间
            .build()
    }
    .respectCacheHeaders(false)
    .build()

5.2 使用 SubcomposeLayout 延迟测量

对于需要根据子组件尺寸来布局的复杂场景，使用 SubcomposeLayout 可以避免多次测量：

@Composable
fun AdaptiveLayout(
    mainContent: @Composable () -> Unit,
    overlay: @Composable (IntSize) -> Unit
) {
    SubcomposeLayout { constraints ->
        val mainPlaceable = subcompose("main", mainContent)
            .first().measure(constraints)
        val overlayPlaceable = subcompose("overlay") {
            overlay(IntSize(mainPlaceable.width, mainPlaceable.height))
        }.first().measure(constraints)
        layout(mainPlaceable.width, mainPlaceable.height) {
            mainPlaceable.place(0, 0)
            overlayPlaceable.place(0, 0)
        }
    }
}

六、性能监控：用工具发现问题

优化要有数据支撑，以下工具帮助你精准定位性能瓶颈。

6.1 Android Studio 重组高亮

在 Android Studio 中启用 Layout Inspector → Recomposition Counts，实时查看每个可组合函数的重组次数，快速找到热点函数。

6.2 使用 Macrobenchmark 测量启动和滚动

@RunWith(AndroidJUnit4::class)
class ScrollBenchmark {
    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun scrollLatency() = benchmarkRule.measureRepeated(
        packageName = "com.example.app",
        metrics = listOf(FrameTimingMetric()),
        iterations = 5,
        setupBlock = { startActivityAndWait() }
    ) {
        val recycler = device.findObject(By.res("product_list"))
        recycler.setGestureMargin(device.displayWidth / 5)
        repeat(3) {
            recycler.fling(Direction.DOWN)
            device.waitForIdle()
        }
    }
}

6.3 Baseline Profiles 提升启动性能

为关键代码路径生成 Baseline Profile，让 ART 在安装时预编译热路径，显著提升冷启动速度（通常可提升 20-40%）：

// 在 macrobenchmark 模块中
@ExperimentalBaselineProfilesApi
class BaselineProfileGenerator {
    @get:Rule
    val baselineRule = BaselineProfileRule()

    @Test
    fun startup() = baselineRule.collectBaselineProfile(
        packageName = "com.example.app"
    ) {
        startActivityAndWait()
        // 模拟用户关键路径操作
    }
}

七、总结与优化清单

Compose 性能优化是一个系统工程，需要从架构设计到代码细节全面考量。以下是一份实用的优化 Checklist：

✅ 使用 @Immutable / @Stable 标注数据类，确保参数稳定性
✅ 用 Compose 编译器报告检查所有可组合函数是否为 skippable
✅ 将状态保持在最小作用域，避免顶层状态导致全量重组
✅ 使用 derivedStateOf 处理派生状态
✅ LazyList 始终提供稳定的 key 和 contentType
✅ 优先使用 graphicsLayer 执行动画，避免每帧重组
✅ 配置 Coil 内存/磁盘缓存，避免重复网络请求
✅ 使用 Macrobenchmark + FrameTimingMetric 量化滚动性能
✅ 为生产 App 添加 Baseline Profiles 提升冷启动速度

性能优化没有银弹，关键是建立"测量 → 定位 → 优化 → 验证"的闭环。希望本文的实战技巧能帮助你的 Compose 应用达到 60fps 流畅体验！

大模型RAG检索增强生成实战：从原理到落地的完整开发指南

Wed, 22 Apr 2026 10:17:15 +0800

一、什么是 RAG？为什么它如此重要

RAG（Retrieval-Augmented Generation，检索增强生成）是一种将信息检索与大语言模型生成能力相结合的技术架构。传统大模型存在两个核心痛点：知识截止日期（训练数据有时效性）和幻觉问题（模型会编造不存在的事实）。RAG 通过在生成前先从外部知识库检索相关内容，将其作为上下文传入模型，从根本上缓解了这两个问题。

RAG 的典型应用场景包括：

企业内部知识问答系统（对接公司文档、Wiki、FAQ）
智能客服（实时检索产品手册、政策文件）
代码助手（检索私有代码库和文档）
医疗/法律等专业领域问答（检索权威文献库）

二、RAG 核心架构与工作流程

一个完整的 RAG 系统由以下几个核心组件构成：

文档加载器（Document Loader）：支持 PDF、Word、Markdown、网页等多种格式
文本分块器（Text Splitter）：将长文档切分为合适的片段（Chunk）
Embedding 模型：将文本转换为高维向量表示
向量数据库（Vector Store）：存储和检索向量，常用 Chroma、Milvus、Pinecone
检索器（Retriever）：根据用户查询找出最相关的文档片段
生成器（Generator）：将检索结果与问题拼接成 Prompt 调用 LLM 生成答案

工作流程如下：用户提问 → 查询向量化 → 向量数据库相似度检索 → 拼接 Prompt → LLM 生成答案 → 返回结果。

三、关键技术选型与优化策略

RAG 系统的效果很大程度上取决于以下几个关键决策：

3.1 文档分块策略

分块大小直接影响检索精度与召回率。经验值：chunk_size=512~1024 tokens，chunk_overlap=50~100 tokens。对于结构化文档，建议按段落或标题层级分块；对于代码文档，按函数或类分块效果更好。

3.2 Embedding 模型选择

中文场景优先考虑：BAAI/bge-large-zh-v1.5、text2vec-large-chinese
多语言场景：multilingual-e5-large
OpenAI API：text-embedding-3-large（效果最佳但有成本）

3.3 检索优化

混合检索：结合向量检索（语义）和 BM25 检索（关键词），用 RRF 融合排序
重排序（Reranker）：用 cross-encoder 模型对 Top-K 结果重新打分
查询扩展：对用户查询进行改写或生成多个子查询

四、Python 实战：用 LangChain 构建 RAG 系统

下面是一个基于 LangChain + Chroma + OpenAI 的完整 RAG 示例：

from langchain.document_loaders import PyPDFLoader, DirectoryLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.embeddings import HuggingFaceEmbeddings
from langchain.vectorstores import Chroma
from langchain.chains import RetrievalQA
from langchain.llms import OpenAI

# 1. 加载文档
loader = DirectoryLoader('./docs', glob='**/*.pdf', loader_cls=PyPDFLoader)
documents = loader.load()
print(f"加载了 {len(documents)} 个文档页面")

# 2. 文本分块
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=512,
    chunk_overlap=64,
    separators=["\n\n", "\n", "。", "！", "？", " "]
)
chunks = text_splitter.split_documents(documents)
print(f"切分为 {len(chunks)} 个文本块")

# 3. 创建 Embedding 模型（使用本地模型，无需 API key）
embeddings = HuggingFaceEmbeddings(
    model_name="BAAI/bge-large-zh-v1.5",
    model_kwargs={"device": "cuda"},  # 有 GPU 时使用
    encode_kwargs={"normalize_embeddings": True}
)

# 4. 构建向量数据库
vectorstore = Chroma.from_documents(
    documents=chunks,
    embedding=embeddings,
    persist_directory="./chroma_db"
)
vectorstore.persist()
print("向量数据库构建完成")

# 5. 构建检索链
retriever = vectorstore.as_retriever(
    search_type="mmr",  # 最大边际相关性，减少冗余
    search_kwargs={"k": 5, "fetch_k": 20}
)

# 6. 构建 QA 链
qa_chain = RetrievalQA.from_chain_type(
    llm=OpenAI(temperature=0),
    chain_type="stuff",
    retriever=retriever,
    return_source_documents=True,
    verbose=True
)

# 7. 问答
result = qa_chain({"query": "请解释产品的退款政策"})
print("答案:", result["result"])
print("来源文档:", [doc.metadata for doc in result["source_documents"]])

上述代码涵盖了完整的 RAG 流水线。在生产环境中，建议将向量数据库替换为 Milvus 或 Weaviate 以支持更大规模数据。

五、常见问题与解决方案

在实际落地过程中，RAG 系统经常遇到以下问题：

检索不准确：优先检查 Embedding 模型是否与文档语言匹配，考虑加入混合检索和 Reranker
答案幻觉仍然存在：在 Prompt 中明确要求模型只基于检索内容回答，无信息时说"不知道"
响应速度慢：向量检索建议使用 HNSW 索引；Embedding 计算可异步或缓存
上下文窗口超限：控制检索数量（Top-K=3~5），或使用 Map-Reduce / Refine chain
文档更新同步：建议设计增量更新机制，使用文档 hash 判断是否需要重新 Embedding

RAG 并非银弹，它更适合"知识密集型"场景。对于逻辑推理、数学计算等任务，Fine-tuning 或 Tool Use 可能是更好的选择。随着 LLM 上下文窗口不断增大（如 Gemini 1M token），未来 RAG 的架构形态也会持续演进，但其核心价值——让模型获取实时、可靠、私有知识——将长期存在。

Android Jetpack Compose 实战：从零构建一个完整的 ToDo 应用

Tue, 21 Apr 2026 08:13:52 +0800

Jetpack Compose 已经从“尝鲜”阶段进入了主流 Android 开发的视野。越来越多的团队开始在新项目中使用 Compose，但很多开发者在真正上手时才发现：看懂文档是一回事，写出能跑的完整应用又是另一回事。

本文用一个真实的 ToDo 应用作为载体，从项目搭建到最终运行，完整走一遍 Compose 开发流程，包括状态管理、数据持久化、MVVM 架构、UI 交互等核心知识点，并附上踩坑记录。

一、项目结构与依赖配置

先看整体项目结构，我们按照标准 MVVM 分层：

app/
├── data/
│   ├── Task.kt
│   ├── TaskDao.kt
│   └── TaskDatabase.kt
├── repository/
│   └── TaskRepository.kt
├── viewmodel/
│   └── TaskViewModel.kt
└── ui/
    ├── MainActivity.kt
    ├── TaskListScreen.kt
    └── AddTaskScreen.kt

在 build.gradle.kts 中添加依赖：

android {
    compileSdk = 34
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.8"
    }
    buildFeatures { compose = true }
}
dependencies {
    val composeBom = platform("androidx.compose:compose-bom:2024.02.00")
    implementation(composeBom)
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    val roomVersion = "2.6.1"
    implementation("androidx.room:room-runtime:$roomVersion")
    implementation("androidx.room:room-ktx:$roomVersion")
    ksp("androidx.room:room-compiler:$roomVersion")
    implementation("androidx.navigation:navigation-compose:2.7.6")
}

踩坑提示：Compose 编译器版本必须与 Kotlin 版本严格对应。

二、数据层：Room 数据库实现

@Entity(tableName = "tasks")
data class Task(
    @PrimaryKey(autoGenerate = true)
    val id: Int = 0,
    val title: String,
    val description: String = "",
    val isCompleted: Boolean = false,
    val createdAt: Long = System.currentTimeMillis()
)

@Dao
interface TaskDao {
    @Query("SELECT * FROM tasks ORDER BY createdAt DESC")
    fun getAllTasks(): Flow>
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertTask(task: Task)
    @Update
    suspend fun updateTask(task: Task)
    @Delete
    suspend fun deleteTask(task: Task)
}

三、Repository 与 ViewModel

class TaskRepository(private val taskDao: TaskDao) {
    val allTasks: Flow> = taskDao.getAllTasks()
    suspend fun insertTask(task: Task) = taskDao.insertTask(task)
    suspend fun updateTask(task: Task) = taskDao.updateTask(task)
    suspend fun deleteTask(task: Task) = taskDao.deleteTask(task)
}

class TaskViewModel(application: Application) : AndroidViewModel(application) {
    private val repository: TaskRepository
    val allTasks: StateFlow>
    var newTaskTitle by mutableStateOf("")
        private set
    init {
        val db = TaskDatabase.getDatabase(application)
        repository = TaskRepository(db.taskDao())
        allTasks = repository.allTasks
            .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
    }
    fun addTask() {
        if (newTaskTitle.isBlank()) return
        viewModelScope.launch {
            repository.insertTask(Task(title = newTaskTitle.trim()))
            newTaskTitle = ""
        }
    }
    fun toggleTaskCompletion(task: Task) {
        viewModelScope.launch { repository.updateTask(task.copy(isCompleted = !task.isCompleted)) }
    }
    fun deleteTask(task: Task) {
        viewModelScope.launch { repository.deleteTask(task) }
    }
}

踩坑提示：在 Compose 里推荐用 StateFlow + collectAsStateWithLifecycle()，能感知生命周期，避免在后台仍然收集数据浪费资源。

四、UI 层：任务列表页面

@Composable
fun TaskListScreen(viewModel: TaskViewModel = viewModel(), onNavigateToAdd: () -> Unit) {
    val tasks by viewModel.allTasks.collectAsStateWithLifecycle()
    Scaffold(
        topBar = { TopAppBar(title = { Text("我的待办") }) },
        floatingActionButton = {
            FloatingActionButton(onClick = onNavigateToAdd) {
                Icon(Icons.Default.Add, contentDescription = "添加任务")
            }
        }
    ) { paddingValues ->
        if (tasks.isEmpty()) {
            Box(modifier = Modifier.fillMaxSize().padding(paddingValues), contentAlignment = Alignment.Center) {
                Text("暂无任务，点击右下角添加")
            }
        } else {
            LazyColumn(modifier = Modifier.padding(paddingValues), contentPadding = PaddingValues(16.dp)) {
                items(tasks, key = { it.id }) { task ->
                    TaskItem(task = task, onToggle = { viewModel.toggleTaskCompletion(task) }, onDelete = { viewModel.deleteTask(task) })
                }
            }
        }
    }
}

@Composable
fun TaskItem(task: Task, onToggle: () -> Unit, onDelete: () -> Unit) {
    Card(modifier = Modifier.fillMaxWidth().padding(vertical = 4.dp)) {
        Row(modifier = Modifier.padding(12.dp), verticalAlignment = Alignment.CenterVertically) {
            Checkbox(checked = task.isCompleted, onCheckedChange = { onToggle() })
            Text(task.title, modifier = Modifier.weight(1f),
                textDecoration = if (task.isCompleted) TextDecoration.LineThrough else TextDecoration.None)
            IconButton(onClick = onDelete) {
                Icon(Icons.Default.Delete, contentDescription = "删除")
            }
        }
    }
}

五、添加任务页面与导航配置

@Composable
fun AddTaskScreen(viewModel: TaskViewModel = viewModel(), onTaskAdded: () -> Unit) {
    Scaffold(topBar = { TopAppBar(title = { Text("添加任务") }) }) { paddingValues ->
        Column(modifier = Modifier.fillMaxSize().padding(paddingValues).padding(16.dp)) {
            OutlinedTextField(
                value = viewModel.newTaskTitle,
                onValueChange = { viewModel.newTaskTitle = it },
                label = { Text("任务名称") },
                modifier = Modifier.fillMaxWidth()
            )
            Button(onClick = { viewModel.addTask(); onTaskAdded() },
                modifier = Modifier.fillMaxWidth().padding(top = 16.dp),
                enabled = viewModel.newTaskTitle.isNotBlank()) {
                Text("保存任务")
            }
        }
    }
}

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            TodoAppTheme {
                val navController = rememberNavController()
                NavHost(navController, startDestination = "list") {
                    composable("list") { TaskListScreen(onNavigateToAdd = { navController.navigate("add") }) }
                    composable("add") { AddTaskScreen(onTaskAdded = { navController.popBackStack() }) }
                }
            }
        }
    }
}

六、常见踩坑总结

remember vs rememberSaveable：remember 在重组时保持状态，横竖屏切换后会丢失；需要跨配置变更保留状态用 rememberSaveable。
LazyColumn key 参数：一定要给 items 传 key 参数，否则列表更新时动画不正确。
Modifier 顺序很重要：.padding().clickable() 和 .clickable().padding() 效果完全不同。
AndroidViewModel 与 ViewModel：需要访问 Context 时用 AndroidViewModel，否则普通 ViewModel 即可。

七、扩展方向

优先级与分类：给 Task 增加 priority 和 category 字段，UI 上用颜色区分
截止日期提醒：集成 WorkManager 设置本地通知
Widget 支持：使用 Glance API 在桌面展示待办列表
深色模式：Material3 自动支持动态主题，只需在 Theme.kt 中开启 dynamicColor = true

如果在实际项目中遇到其他 Compose 相关问题，欢迎留言交流！

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

Mon, 20 Apr 2026 10:39:38 +0800

为什么要在 Android 项目中引入 Hilt？

依赖注入（Dependency Injection，DI）是现代 Android 开发中几乎无法绕开的话题。手动管理对象依赖不仅繁琐，还容易在 Activity/Fragment 生命周期中引发内存泄漏。Google 官方推荐的 Hilt 框架基于 Dagger2，通过编译期代码生成，在保持高性能的同时大幅降低了上手门槛。

本文以一个真实的“用户登录 + 数据加载”功能为线索，带你从零搞建一套符合 Clean Architecture 的 Hilt 注入体系，覆盖以下场景：

ViewModel 中注入 Repository
Repository 中注入 Retrofit 和 Room
多模块项目中的跨模块注入
单元测试中替换真实依赖

第一步：添加依赖与基础配置

在项目根目录 build.gradle 中添加 Hilt 插件：

// 根目录 build.gradle
plugins {
    id 'com.google.dagger.hilt.android' version '2.51.1' apply false
}

在 app 模块 build.gradle 中：

plugins {
    id 'com.google.dagger.hilt.android'
    id 'kotlin-kapt'
}

dependencies {
    implementation "com.google.dagger:hilt-android:2.51.1"
    kapt "com.google.dagger:hilt-android-compiler:2.51.1"
    implementation "androidx.hilt:hilt-navigation-compose:1.2.0"
}

接着给 Application 类加上 @HiltAndroidApp 注解，这是 Hilt 的入口，不能省略：

@HiltAndroidApp
class MyApp : Application()

别忘了在 AndroidManifest.xml 中指定 android:name=".MyApp"。

第二步：构建 Network 和 Database 模块

Hilt 通过 @Module + @InstallIn 来声明如何提供依赖。网络层和数据库层通常作用域为整个应用生命周期，使用 SingletonComponent：

@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {

    @Provides
    @Singleton
    fun provideOkHttpClient(): OkHttpClient {
        return OkHttpClient.Builder()
            .addInterceptor(HttpLoggingInterceptor().apply {
                level = HttpLoggingInterceptor.Level.BODY
            })
            .connectTimeout(30, TimeUnit.SECONDS)
            .build()
    }

    @Provides
    @Singleton
    fun provideRetrofit(okHttpClient: OkHttpClient): Retrofit {
        return Retrofit.Builder()
            .baseUrl("https://api.example.com/")
            .client(okHttpClient)
            .addConverterFactory(GsonConverterFactory.create())
            .build()
    }

    @Provides
    @Singleton
    fun provideUserApi(retrofit: Retrofit): UserApi {
        return retrofit.create(UserApi::class.java)
    }
}

数据库模块同理：

@Module
@InstallIn(SingletonComponent::class)
object DatabaseModule {

    @Provides
    @Singleton
    fun provideDatabase(@ApplicationContext context: Context): AppDatabase {
        return Room.databaseBuilder(
            context,
            AppDatabase::class.java,
            "app_database"
        ).build()
    }

    @Provides
    fun provideUserDao(database: AppDatabase): UserDao {
        return database.userDao()
    }
}

踩坑提示：UserDao 不加 @Singleton，因为 Room 会自己管理 DAO 的生命周期，重复包装反而可能引发问题。

第三步：注入 Repository 和 ViewModel

Repository 层负责整合网络和本地数据源，使用构造函数注入：

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

    fun getCachedUser(): Flow<User?> = userDao.getUser()
}

ViewModel 中使用 @HiltViewModel + @Inject constructor，无需手动创建 ViewModelFactory：

@HiltViewModel
class LoginViewModel @Inject constructor(
    private val userRepository: UserRepository
) : ViewModel() {

    private val _loginState = MutableStateFlow<LoginState>(LoginState.Idle)
    val loginState: StateFlow<LoginState> = _loginState.asStateFlow()

    fun login(username: String, password: String) {
        viewModelScope.launch {
            _loginState.value = LoginState.Loading
            val result = userRepository.login(username, password)
            _loginState.value = if (result.isSuccess) {
                LoginState.Success(result.getOrNull()!!)
            } else {
                LoginState.Error(result.exceptionOrNull()?.message ?: "登录失败")
            }
        }
    }
}

在 Activity/Fragment 中获取 ViewModel 只需：

@AndroidEntryPoint
class LoginActivity : AppCompatActivity() {
    private val viewModel: LoginViewModel by viewModels()
}

注意 Activity 必须加 @AndroidEntryPoint，否则 Hilt 无法注入。

第四步：单元测试中替换依赖

Hilt 对测试的支持非常完善，通过 @TestInstallIn 可以替换正式模块：

@TestInstallIn(
    components = [SingletonComponent::class],
    replaces = [NetworkModule::class]
)
@Module
object FakeNetworkModule {

    @Provides
    @Singleton
    fun provideUserApi(): UserApi = FakeUserApi()
}

测试类：

@HiltAndroidTest
class LoginViewModelTest {

    @get:Rule
    var hiltRule = HiltAndroidRule(this)

    @Inject
    lateinit var userRepository: UserRepository

    @Before
    fun init() {
        hiltRule.inject()
    }

    @Test
    fun testLoginSuccess() = runTest {
        val viewModel = LoginViewModel(userRepository)
        viewModel.login("test_user", "password123")
        assertTrue(viewModel.loginState.value is LoginState.Success)
    }
}

常见问题与最佳实践

作用域选择：Activity 内的依赖用 ActivityComponent，避免 Singleton 持有 Activity 引用造成泄漏
@Qualifier 区分同类型：若有多个 OkHttpClient，用 @Named 或自定义 Qualifier 区分
懒加载：用 Lazy<T> 包装不需要立即初始化的依赖，减少启动耗时
多模块项目：每个 feature 模块可以有自己的 @InstallIn(ActivityComponent::class) 模块，Hilt 会自动合并
kapt 编译慢？：升级到 KSP 可以显著提升编译速度，Hilt 已支持 KSP

掌握这套模式后，你会发现代码可测试性、可维护性都有质的提升。依赖注入不只是框架的使用，更是一种面向接口编程的思维方式。

MCP 工具开发实战：10步给 AI 接入任意外部 API

Mon, 20 Apr 2026 10:00:02 +0800

什么是 MCP？

2024 年底，Anthropic 开源了 Model Context Protocol（MCP）——一个让 AI 大模型能够直接调用外部工具、读取数据源的开放协议。它解决了一个核心痛点：如何让 AI 和你的真实世界连通？

比较一下两种方式：

之前：Function Calling —— 每个模型各定一套，接口不通，维护成本高
现在：MCP —— 标准协议，写一次 Server，所有支持 MCP 的 AI 都能用

MCP 的核心优势：

跨模型通用：Clauде、GPT-4、Gemini 共用一套工具
进程隔离：Server 独立运行，崩溃不影响主程序
双向通信：Server 可以主动向 AI 推送消息
生态成熟：GitHub、Slack、PostgreSQL 都已有官方 MCP Server

本文目标：10 步完成一个真实可用的 MCP Server，接入天气 API，在 Claude Desktop 里直接用自然语言查询天气。

环境准备（Step 1-2）

Step 1：确认运行环境

# 需要 Node.js 18+ 或 Python 3.10+
node -v      # v18.0.0 或以上
python3 --version  # 3.10+

本文选用 TypeScript + Node.js（官方 SDK 支持最完善）。

Step 2：创建项目

mkdir weather-mcp-server
cd weather-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk axios
npm install -D typescript @types/node ts-node
npx tsc --init

修改 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "node16",
    "moduleResolution": "node16",
    "outDir": "./dist",
    "strict": true
  }
}

申请天气 API Key（Step 3）

Step 3：获取 OpenWeatherMap API Key

登录 openweathermap.org
免费注册账号 → 进入 My API keys 页面
复制默认生成的 Key（或点 Generate New Key）

免费额度：60 次/分钟，个人使用完全够用。

编写核心代码（Step 4-6）

Step 4：创建 Server 入口文件

新建 src/index.ts：

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import axios from "axios";

const server = new Server(
  { name: "weather-mcp-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

Step 5：注册工具列表

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_weather",
      // 关键：description 要写清楚触发条件，AI 才知道何时调用它
      description:
        "当用户询问某个城市的天气、气温、湿度、风力时调用。返回实时天气数据。",
      inputSchema: {
        type: "object",
        properties: {
          city: {
            type: "string",
            description: "城市名称，支持中文或英文，如：北京、Shanghai、广州",
          },
        },
        required: ["city"],
      },
    },
  ],
}));

Step 6：实现工具逻辑

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name !== "get_weather") {
    throw new Error("未知工具");
  }

  const city = request.params.arguments?.city as string;
  const apiKey = process.env.WEATHER_API_KEY;

  if (!apiKey) {
    return {
      content: [{ type: "text", text: "错误：WEATHER_API_KEY 未设置" }],
      isError: true,
    };
  }

  try {
    const { data } = await axios.get(
      "https://api.openweathermap.org/data/2.5/weather",
      {
        params: { q: city, appid: apiKey, units: "metric", lang: "zh_cn" },
        timeout: 5000,
      }
    );

    const result = {
      城市: data.name,
      天气: data.weather[0].description,
      温度: `${data.main.temp}°C`,
      湿度: `${data.main.humidity}%`,
      风速: `${data.wind.speed} m/s`,
      气压: `${data.main.pressure} hPa`,
    };

    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  } catch (err: any) {
    const msg = err.response?.status === 404
      ? `找不到城市: ${city}`
      : `查询失败: ${err.message}`;
    return { content: [{ type: "text", text: msg }], isError: true };
  }
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server 已启动");
}

main().catch(console.error);

编译与本地测试（Step 7）

Step 7：编译并运行

npx tsc
WEATHER_API_KEY=your_api_key node dist/index.js

启动成功应输出：Weather MCP Server 已启动（输到 stderr）

验证工具注册（新开一个终端）：

# 发送一个 ListTools 请求
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | WEATHER_API_KEY=xxx node dist/index.js

接入 Claude Desktop（Step 8-9）

Step 8：找到配置文件

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%Claudeclaude_desktop_config.json

Step 9：添加 Server 配置

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/绝对路径/weather-mcp-server/dist/index.js"],
      "env": {
        "WEATHER_API_KEY": "你的_API_KEY"
      }
    }
  }
}

保存后 重启 Claude Desktop，在输入框左下角能看到工具图标，点开可看到 get_weather 已注册。

现在对 Claude 说“北京今天天气怎么样？”，它会自动调用你写的 MCP Server。

验证与排错（Step 10）

Step 10：常见问题排查

工具图标不出现：配置文件路径错误，或 JSON 格式有问题。用 JSON 校验器检查。

Server 启动报错但 Claude 无提示：

# 单独运行查报错
node dist/index.js

# 查看 Claude 日志
# macOS
tail -f ~/Library/Logs/Claude/main.log

AI 不调用工具：这通常是 description 写得不够清楚。要明确写出触发条件，比如“当用户询问某城市天气时调用”。

返回内容太长导致对话卡顿：MCP 返回内容会进入上下文。只返回关键字段，不要把整个原始 API 响应招过来。

进阶扩展

掌握基础后，MCP 还支持更多能力：

Resources（资源）：让 AI 读取文件、数据库，适合大量数据场景
Prompts（模板）：预置常用 Prompt，用户可直接调用
Sampling（采样）：Server 主动让 AI 生成内容（高级用法）

建议从一个你日常需要的 API 开始实践：公司内部系统、个人数据库、家庭自动化接口……把它接入 AI，你会发现工作效率就是不一样。

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

Sat, 18 Apr 2026 08:08:13 +0800

什么是 MCP？为什么它能让 AI 接入任意 API

MCP（Model Context Protocol）是 Anthropic 于 2024 年底开源的一套标准化协议，专门用于解决一个老大难问题：如何让 AI 助手安全、可复用地调用外部工具与 API？

在 MCP 出现之前，每个 AI 应用都要自己实现工具调用逻辑，格式五花八门，维护成本极高。MCP 相当于给 AI 工具调用定义了一套"USB 接口标准"——只要遵循协议，任何工具都能即插即用。

目前已有大量开源社区 MCP Server 覆盖常见场景：浏览器自动化、数据库查询、GitHub 操作、Slack 消息、Google Drive 等。本文将带你从零实现一个能查询天气的 MCP Server，并与 Claude Desktop 集成。

环境准备与项目初始化

本教程使用 TypeScript + Node.js 实现 MCP Server。首先确认环境：

node -v   # 需要 v18+
npm -v    # 需要 v9+

创建项目并安装依赖：

mkdir my-weather-mcp && cd my-weather-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node ts-node
npx tsc --init

修改 tsconfig.json，确保以下配置：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  }
}

实现核心：编写 MCP Server

创建 src/index.ts，这是整个 Server 的入口：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "weather-server",
  version: "1.0.0",
});

// 定义工具：查询天气
server.tool(
  "get_weather",
  "查询指定城市的当前天气",
  {
    city: z.string().describe("城市名称，例如：Beijing、Shanghai"),
    units: z.enum(["metric", "imperial"]).default("metric").describe("温度单位：metric=摄氏度，imperial=华氏度"),
  },
  async ({ city, units }) => {
    // 调用 Open-Meteo 免费 API（无需 API Key）
    const geocodeRes = await fetch(
      `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1&language=zh&format=json`
    );
    const geocodeData = await geocodeRes.json() as any;
    
    if (!geocodeData.results?.length) {
      return { content: [{ type: "text", text: `找不到城市：${city}` }] };
    }
    
    const { latitude, longitude, name, country } = geocodeData.results[0];
    const tempUnit = units === "metric" ? "celsius" : "fahrenheit";
    
    const weatherRes = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,relative_humidity_2m,wind_speed_10m,weather_code&temperature_unit=${tempUnit}`
    );
    const weatherData = await weatherRes.json() as any;
    const current = weatherData.current;
    
    const tempSymbol = units === "metric" ? "°C" : "°F";
    return {
      content: [{
        type: "text",
        text: `${name}, ${country} 当前天气：\n温度：${current.temperature_2m}${tempSymbol}\n湿度：${current.relative_humidity_2m}%\n风速：${current.wind_speed_10m} km/h`
      }]
    };
  }
);

// 定义资源：暴露支持的城市列表
server.resource(
  "supported-cities",
  "weather://supported-cities",
  async () => ({
    contents: [{
      uri: "weather://supported-cities",
      text: "支持全球任意城市，使用英文或拼音输入城市名即可。常用：Beijing, Shanghai, Shenzhen, Guangzhou, Chengdu"
    }]
  })
);

// 启动 Server（Stdio 模式，供 Claude Desktop 调用）
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server 已启动");
}

main().catch(console.error);

注意几个关键点：

McpServer 是 SDK 提供的高层封装，负责处理所有 MCP 协议细节
server.tool() 第三个参数用 zod 定义参数 schema，AI 会根据这个生成调用参数
StdioServerTransport 表示通过标准输入输出通信，是 Claude Desktop 默认的连接方式
我们使用了 Open-Meteo 的完全免费 API，无需注册，无需 API Key，适合学习使用

编译与本地测试

编译 TypeScript：

npx tsc

用 MCP Inspector 快速测试（官方调试工具）：

npx @modelcontextprotocol/inspector node dist/index.js

浏览器打开 http://localhost:5173，在 Inspector 界面中点击 "Connect" 连接到你的 Server，然后找到 get_weather 工具，输入 {"city": "Shanghai"} 测试：

# 预期输出（成功）：
Shanghai, China 当前天气：
温度：22.5°C
湿度：68%
风速：12.3 km/h

如果看到这样的输出，说明 MCP Server 工作正常！

接入 Claude Desktop

找到 Claude Desktop 的配置文件并编辑：

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

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/绝对路径/my-weather-mcp/dist/index.js"],
      "env": {}
    }
  }
}

重启 Claude Desktop，在对话框左下角会看到一个锤子图标（工具列表），点击可见 get_weather 工具已加载。现在对 Claude 说"帮我查一下深圳今天的天气"，它会自动调用你的 MCP Server！

进阶：添加 Prompt 模板和错误处理

MCP 还支持 server.prompt()，预定义对话模板：

server.prompt(
  "weather-report",
  "生成一份完整的天气播报",
  {
    city: z.string(),
    date: z.string().optional().describe("日期，默认今天"),
  },
  ({ city, date }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `请用专业播音员的口吻，为 ${city} 生成 ${date ?? "今天"} 的天气播报，包括穿衣建议和出行提示。`
      }
    }]
  })
);

生产环境中，还需要做好错误处理和日志记录：

// 所有对外请求都包裹 try/catch
try {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
  // ...
} catch (err) {
  return {
    content: [{ type: "text", text: `查询失败：${(err as Error).message}` }],
    isError: true  // 标记为错误响应，让 AI 知道需要重试或提示用户
  };
}

常见踩坑与解决方案

Claude Desktop 看不到工具：检查配置文件路径是否用了绝对路径，相对路径无效；确认 JSON 格式正确，可用 node -e "require('./config.json')" 验证
Server 启动就崩溃：记住不要在 Server 中用 console.log，Stdio 模式下标准输出是 MCP 协议通道，调试信息必须用 console.error
工具参数识别不准：优化 zod 中的 .describe() 文字，AI 靠这些描述理解参数含义；参数描述越详细，AI 传值越准确
异步工具超时：Claude Desktop 默认超时较短，耗时操作建议加进度提示，或将大任务拆分为多个小工具串联调用
部署到服务器后无法连接：Stdio 模式只支持本地进程通信；需要远程调用则切换为 SSEServerTransport（HTTP + Server-Sent Events 模式）

Jetpack Compose 性能优化实战：5个高频坑与解决方案

Thu, 16 Apr 2026 09:51:25 +0800

Jetpack Compose 已经成为 Android 原生 UI 开发的主流方案，但很多开发者在实际项目落地时都踩过同一批坑：动画卡顿、状态管理混乱、性能优化无从下手。本文基于真实项目经验，整理出 Compose 开发中最高频的性能问题及解决方案，并附上可直接复用的代码片段。

一、搞清楚 Recomposition 的触发机制

Compose 性能问题十有八九出在不必要的重组（Recomposition）上。很多开发者误以为只要用了 remember 就够了，实际上 Compose 的重组粒度取决于 Composable 函数读取了哪些 State。

最常见的反模式是把整个复杂对象作为 State 传入：

// ❌ 错误：整个 UserInfo 变化都会触发 ProfileCard 重组
@Composable
fun ProfileCard(userInfo: UserInfo) {
    Text(userInfo.name)
    Text(userInfo.email)
}

// ✅ 正确：只传需要的字段，减少重组范围
@Composable
fun ProfileCard(name: String, email: String) {
    Text(name)
    Text(email)
}

另一个高频问题是 Lambda 引用不稳定。每次父组件重组时，传入的 Lambda 都会产生新实例，导致子组件被强制重组：

// ❌ 每次重组都创建新 Lambda
LazyColumn {
    items(list) { item ->
        ItemCard(item, onClick = { viewModel.onItemClick(item) })
    }
}

// ✅ 用 remember 缓存 Lambda（Kotlin 1.9+ 可用 rememberUpdatedState）
val onItemClick = remember { { item: Item -> viewModel.onItemClick(item) } }

调试工具推荐：在 Android Studio 开启 Layout Inspector → Recomposition Counts，能直观看到每个节点的重组次数，快速定位热点。

二、LazyColumn 的正确打开方式

LazyColumn 是 Compose 里最容易出性能问题的组件，核心原则是：给每个 item 提供稳定唯一的 key。

// ❌ 没有 key，列表增删时会全量重组
LazyColumn {
    items(messageList) { msg ->
        MessageItem(msg)
    }
}

// ✅ 提供 key，Compose 可以精准复用已有组件
LazyColumn {
    items(
        items = messageList,
        key = { msg -> msg.id }  // 必须是唯一稳定值
    ) { msg ->
        MessageItem(msg)
    }
}

另一个坑点：在 item 内部做复杂计算。LazyColumn 滚动时会频繁调用 item 的 Composable，应把耗时逻辑移到 ViewModel 或用 remember(key) 缓存：

@Composable
fun MessageItem(msg: Message) {
    // ❌ 每次重组都计算
    val formattedTime = SimpleDateFormat("HH:mm").format(msg.timestamp)
    
    // ✅ key 不变就不重算
    val formattedTime = remember(msg.timestamp) {
        SimpleDateFormat("HH:mm", Locale.getDefault()).format(msg.timestamp)
    }
    
    Text(formattedTime)
}

对于图片加载，务必配合 contentScale 和固定尺寸，避免 Coil/Glide 加载完成后触发重新布局：

AsyncImage(
    model = msg.avatarUrl,
    contentDescription = null,
    modifier = Modifier.size(40.dp),  // 固定尺寸！
    contentScale = ContentScale.Crop
)

三、状态提升与 ViewModel 的配合

Compose 推崇"状态提升（State Hoisting）"，但很多人做过头了——把所有状态都塞进 ViewModel，导致 UI 层完全依赖 ViewModel 才能预览，测试也变得复杂。

实用原则：局部 UI 状态留在 Composable，业务状态交给 ViewModel。

// 局部 UI 状态（展开/折叠）不需要进 ViewModel
@Composable
fun ExpandableCard(title: String, content: String) {
    var expanded by remember { mutableStateOf(false) }
    
    Card(onClick = { expanded = !expanded }) {
        Column {
            Text(title)
            AnimatedVisibility(visible = expanded) {
                Text(content)
            }
        }
    }
}

// 业务数据从 ViewModel 的 StateFlow 收集
@Composable
fun ArticleScreen(viewModel: ArticleViewModel = hiltViewModel()) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
    
    when (uiState) {
        is Loading -> LoadingIndicator()
        is Success -> ArticleList((uiState as Success).articles)
        is Error -> ErrorView((uiState as Error).message)
    }
}

注意：使用 collectAsStateWithLifecycle() 而非 collectAsState()，前者在 Activity 进入后台时会自动停止收集，节省资源。

四、动画性能：用 derivedStateOf 避免过度重组

滚动联动动画是 Compose 的高频需求，但如果直接监听 lazyListState.firstVisibleItemScrollOffset，会在每一帧都触发重组：

val listState = rememberLazyListState()

// ❌ 每像素都重组
val showFab = listState.firstVisibleItemIndex > 0

// ✅ 只有结果变化时才重组
val showFab by remember {
    derivedStateOf { listState.firstVisibleItemIndex > 0 }
}

AnimatedVisibility(visible = showFab) {
    FloatingActionButton(onClick = { /* scroll to top */ }) {
        Icon(Icons.Default.ArrowUpward, contentDescription = "回到顶部")
    }
}

derivedStateOf 的核心价值：将高频 State 变化转换为低频结果变化，是处理滚动、拖拽等连续手势的必备工具。

五、实战踩坑记录

以下是真实项目中遇到的几个典型问题：

坑1：Dialog 内容闪烁。根因是 Dialog 的内容 Composable 和触发状态在同一层，点击按钮时状态先变 false 再销毁，导致闪一帧空内容。解决方案：用 AnimatedVisibility 替代直接条件渲染，或用 DialogProperties(dismissOnBackPress = true) 配合独立的 showDialog 状态管理。
坑2：TextField 输入卡顿。在低端机上 TextField 每次输入都卡，排查发现是 onValueChange 里做了字符串格式化操作（手机号分段显示），格式化逻辑本身是 O(n) 但触发了整个父组件重组。解决：把格式化逻辑移入 remember(value) { ... }，并把 TextField 封装成独立组件隔离重组影响。
坑3：BottomSheet 内 LazyColumn 高度异常。BottomSheet 默认有高度约束，内部 LazyColumn 需要加 .weight(1f) 或指定 fillMaxHeight(0.9f)，否则在某些机型上会只显示一行。
坑4：Dark Mode 切换时动画丢失。系统深色模式切换会重建 Activity（除非在 Manifest 配置了 uiMode），导致 Compose 状态丢失。解决：在 AndroidManifest 的 Activity 节点加 android:configChanges="uiMode" 并在 ViewModel 里持久化关键状态。

Jetpack Compose 的学习曲线主要在于理解其响应式模型和重组机制，一旦建立起正确的心智模型，开发效率会有质的提升。建议结合 Android Studio 的 Profiler 和 Layout Inspector 实际测量，而不是凭感觉优化。