阅读视图

发现新文章,点击刷新页面。

Capacitor + React 的 iOS 侧滑返回手势

Capacitor + React 的 iOS 侧滑返回手势

适用对象:用 Capacitor 把 React SPA 打包成 iOS App,二级页面希望支持系统左侧边缘右滑返回(侧滑返回手势)。

问题的背景

在 WKWebView(Capacitor iOS 容器)里跑 React Router 这类 SPA,经常会遇到:

  • 二级页面无法侧滑返回;
  • 能侧滑但上级页面预览是白屏/黑屏(看不到上一页内容);
  • 自己实现手势(截图 + 叠层 + history.back())会引入大量时序/兼容性坑。

解决的结论:优先用系统能力,而不是自研手势

核心思路:让 WebView 直接启用 WebKit 自带的交互式返回手势。

在 iOS 上,这个开关就是:

webView.allowsBackForwardNavigationGestures = true

这比“自研 edge-pan + snapshot”可靠得多:交互曲线、阈值、上一页预览快照、渲染时机都由系统处理。

最小可用改动(3 步)

下面这 3 步就是本次修复能通过验收的关键(其余优化都可以后放)。

1) 用自定义 CAPBridgeViewController 子类接管 WKWebView 配置

文件:ios/App/App/AppDelegate.swift

  • 新增 AppViewController: CAPBridgeViewController
  • viewDidLoad() 里统一设置背景色(减少“闪白/闪黑”)并启用系统手势:
@objc(AppViewController)
class AppViewController: CAPBridgeViewController {
  override func viewDidLoad() {
    super.viewDidLoad()

    // 设置背景(防止任何空白闪现)
    self.view.backgroundColor = UIColor.systemBackground
    self.webView?.isOpaque = true
    self.webView?.backgroundColor = UIColor.systemBackground
    self.webView?.scrollView.backgroundColor = UIColor.systemBackground

    // 永久启用系统原生侧滑返回手势(最简单、最可靠)
    self.webView?.allowsBackForwardNavigationGestures = true
  }
}

2) storyboard 把初始 VC 指向你的自定义 VC(否则上一步永远不会生效)

文件:ios/App/App/Base.lproj/Main.storyboard

把初始控制器从 Capacitor 的 CAPBridgeViewController 改成你自己的:

  • customClass="AppViewController"
  • customModule="App"

完整示例:

<viewController id="BYZ-38-t0r" customClass="AppViewController" customModule="App" sceneMemberID="viewController"/>

3) Web 侧配合(强烈建议):禁用浏览器自动滚动恢复(减少“返回预览白屏/错位”)

文件:src/App.tsx

useEffect(() => {
  if ('scrollRestoration' in history) {
    history.scrollRestoration = 'manual'
  }
}, [])

原因很简单:系统侧滑返回预览依赖 WebKit 的历史快照,但 SPA 在返回时的“自动滚动恢复”会让快照捕获到不一致/空白的中间态(尤其是列表页、滚动后返回最明显)。

Web 端跳转配置的配合(建议)

  • Tab 根页面之间(例如首页/我的)建议用 replace,避免把 Tab 切换写入回退栈,出现“Tab 之间也能侧滑回退”的反直觉体验。
    • <Link to="/home" replace />navigate('/home', { replace: true })
  • 二级页面(例如设置/资料)保持默认的 push,让它进入历史栈,从而可被系统侧滑返回。

一句话:该 push 的 push,该 replace 的 replace。这决定了 iOS 系统手势到底会回到哪里。

经验与踩坑

  • 优先使用系统 API:自研手势要处理快照时机、渲染竞态、手势冲突、webView.isHidden 黑屏等问题,成本和风险都很高。
  • Native 与 Web 必须联动:WKWebView 的历史栈 + SPA 的路由栈 + 滚动恢复,是同一个系统。
  • 真机 + 滚动场景必测:很多“预览白屏”只有在页面滚动后才会暴露。
  • 背景色是兜底不是解法:它只能减少“闪一下”的主观感受,核心仍是让系统正确拿到历史快照。

keywords

Capacitor iOS swipe back、WKWebView allowsBackForwardNavigationGestures、React Router iOS 手势返回、history.scrollRestoration manual、CAPBridgeViewController 自定义、iOS WebView 返回白屏、Capacitor 返回手势

Swift 6.2 列传(第十七篇):钟灵的“雷电蟒”与测试附件

在这里插入图片描述

摘要:一个失败的测试报告,如果只写着“某某参数错误”,那和一张“失物招领”有什么区别?Swift Testing 新增的 Attachments(附件)功能(ST-0009),就像是给失败的测试现场,打上了一个**“现场取证包”**,直接将调试日志和关键数据附着在报告上,让 Bug 无所遁形。

0️⃣ 🐼 序章:万劫谷的“失灵”现场

万劫谷,一个充满了陷阱和奇门遁甲的虚拟测试环境。

大熊猫侯佩正在谷中寻找他那四根宝贝竹笋的踪迹(它们现在安全地储存在 InlineArray 里),一路上他习惯性地摸了摸头顶,确认自己的黑毛依然茂密,头绝对不秃

他身边站着一个活泼可爱的绿衫少女,正是钟灵。钟灵的特点是天真烂漫,喜欢饲养各种“小宠物”,尤其是她那条能放出电流的“雷电蟒”(现在是她编写的 Character Struct 数据模型)。

在这里插入图片描述

“侯大哥,你看!”钟灵指着屏幕上的测试报告,气得直跺脚,“我的测试又失败了!它明明应该生成一个名为 Rem 的角色,结果生成了 Ram!报告上只写了预期值和实际值,可是这个失败的 Ram 角色内部状态到底是什么?它的 UUID 是多少?我完全不知道!”

侯佩叹了口气:“这就是测试的黑箱困境。失败的报告,就像是你看到一只断了腿的兔子,但不知道它是在哪条路上、被谁咬伤的。我们得找到现场遗留的物证。”

在本次大冒险中,您将学到如下内容:

  • 0️⃣ 🐼 序章:万劫谷的“失灵”现场
  • 1️⃣ 📦 驯服数据:Attachable 协议的契约
  • 2️⃣ 📝 现场取证:Attachment.record() 的铁律
  • 3️⃣ 🚧 侠客的遗憾:现阶段的不足
  • 4️⃣ 🐼 尾声:条件判断的“外功”与“内力”

钟灵急道:“对!我要把我的‘雷电蟒’(数据模型)的全部信息,直接打包塞进这个失败报告里!(Swift Testing: Attachments)”

在这里插入图片描述


1️⃣ 📦 驯服数据:Attachable 协议的契约

要让数据能够被 Swift Testing 系统识别并打包,它必须遵守新的“江湖规矩”:Attachable 协议。

侯佩指导钟灵,将她那可爱的“雷电蟒”数据模型进行武装升级:

import Foundation
import Testing 

// 钟灵的角色结构体,它就是那条“雷电蟒”
struct Character: Codable, Attachable { 
    var id = UUID() // 关键的内部状态,比如角色的唯一标识符
    var name: String
}

在这里插入图片描述

侯佩解释道:“Attachable 协议就像是你给你的宠物签订了一份‘随行契约’。只要有了这个契约,系统就知道在关键时刻,应该如何‘捕捉’和‘打包’它。”

🔑 技术关键点:Codable 的加持 注意,这个 Character 结构体不仅遵循了 Attachable,还遵循了 Codable。对于像结构体这样的自定义数据类型,Swift Testing 会利用 Codable 的能力,将其实例自动编码DataString 格式,然后再进行附加。这样才能确保数据是有头有脸、完整地出现在报告中。

2️⃣ 📝 现场取证:Attachment.record() 的铁律

在这里插入图片描述

现在,钟灵只需要在她的生产代码(Production Code)中生成她的角色:

// 生产代码:生成一个新角色
func makeCharacter() -> Character {
    // 默认生成一个名叫 "Ram" 的角色
    Character(name: "Ram")
}

然后,在测试代码中,无论测试是成功还是失败,她都要确保这个角色的所有状态,都被系统记录下来:

@Test func defaultCharacterNameIsCorrect() {
    let result = makeCharacter()
    
    // 💔 测试失败断言:预期 Rem,实际 Ram
    #expect(result.name == "Rem") 

    // 🎒 关键步骤:记录附件!
    // 将整个 result 实例附着到本次测试结果中,并命名为 "Character"
    Attachment.record(result, named: "Character") 
}

“太神了!”钟灵惊呼道,“当这个测试运行失败时,Xcode 就会自动将这个 result 实例的 JSON 编码数据,直接显示在测试报告的旁边!我一眼就能看到这个失败的 Ram 角色的 UUID 是多少,它的内部状态是不是被某个毒药(Bug)污染了!”

在这里插入图片描述

侯佩点头:“这就叫 ‘证据确凿’。以前你只能 望洋兴叹,现在你可以 一目了然。”

3️⃣ 🚧 侠客的遗憾:现阶段的不足

侯佩作为精通技术的工程师,也指出了这一功能在 Swift 6.2 版本的些许遗憾。

  • 🚫 图像缺失症: “目前,Swift Testing 尚不支持附加图像(Image),”侯佩遗憾地说,“这就像你抓到了一个间谍,却不让你拍下他的照片。如果我做 SwiftUI 界面测试,失败了却不能附上截图,那会让人非常抓狂。”
  • ♻️ 生命周期控制的缺席: “另一个遗憾是,它不像 XCTest 的同类功能那样,支持生命周期控制(Lifetime Controls)。”

“生命周期控制是什么?”钟灵好奇地问。

在这里插入图片描述

“就是如果你的测试成功了,系统可以自动删除你附加的这些日志文件和数据。这样可以保持测试环境的轻量化。现在嘛,你成功了,这些文件还是会留在那,徒增烦恼。”

4️⃣ 🐼 尾声:条件判断的“外功”与“内力”

在这里插入图片描述

解决了附件问题,钟灵的测试调试效率提升了百倍。但她很快又遇到了新的困惑。

“侯大哥,我的宠物‘雷电蟒’需要在不同的硬件环境(例如 M1 芯片和 Intel 芯片)上运行不同的代码。Swift Testing 有一个很方便的功能叫做 ConditionTrait,可以用来定义‘只在 M1 上运行’的测试条件。”

在这里插入图片描述

侯佩点头:“是的,ConditionTrait 是测试的‘内功’,决定测试是否应该被执行。”

钟灵苦恼道:“但是,我能不能在非测试函数(Non-test function),比如我的生产代码里,也引用和判断这个‘内功’?比如,我想写一段普通的函数,判断‘我现在是不是在 M1 芯片上运行?’,并根据结果调整代码逻辑。”

在这里插入图片描述

侯佩眼中闪过一丝精光,他知道,钟灵提出的需求,已经触及到了 Swift Testing 的深层奥秘。

“钟灵姑娘,你提出了一个跨越测试与生产代码边界的哲学问题。你需要的不是附件,而是将测试的‘内功心法’,转化为人人可用的‘外功’招式。”

在这里插入图片描述

(欲知后事如何,且看下回分解:Swift Testing: Public API to evaluate ConditionTrait —— 如何在普通函数中,运用测试框架的‘条件判断’心法。)

在这里插入图片描述

App 暴毙现场直击:如何用 MetricKit 写一份完美的“验尸报告”

在这里插入图片描述

引子

在新深圳(Neo-Shenzhen)第 42 区阴雨连绵的夜晚,王代码(Old Wang)坐在全息屏幕前,手里捏着半截早已熄灭的合成烟草。作为一名在赛博空间摸爬滚打二十年的“数字清道夫”,他见过各种各样的 App 暴毙现场。

“又是 OOM(内存溢出)?”旁边的全息 AI 助手艾达(Ada)一边修剪着并不存在的指甲,一边冷嘲热讽,“你的代码就像这该死的天气一样,总是漏个不停。”

王代码没有理会她的挖苦,只是死死盯着那个被称为 Xcode Organizer 的官方监控面板。它就像个只会打官腔的衙门老头,告诉你结果,却永远不告诉你原因。

在这里插入图片描述

“这老东西只告诉我 App 死了,”王代码指着屏幕上毫无生气的图表骂道,“却不告诉我它是怎么死的。是被系统暗杀了?还是自己吃太饱撑死的?Xcode Organizer 简直就是个‘庸医’。”

在本篇文章中,您将学到如下内容:

  • 引子
  • 🕵️‍♂️ 第 1 幕:告别那个只会报丧的 Xcode Organizer
  • 🧱 第 2 幕:搭建秘密情报网
  • 🩸 第 3 幕:植入间谍(AppDelegate 集成)
  • 💀 第 4 幕:解读死因(Payload 的奥秘)
  • ⏳ 第 5 幕:耐心的猎人
  • 🎬 终章:真相大白

要想在这个代码丛林里活下去,光靠那个“庸医”是不够的。王代码从加密硬盘里掏出了他的秘密武器——MetricKit

“看来,我们得给自己找点更猛的药了。”

在这里插入图片描述


🕵️‍♂️ 第 1 幕:告别那个只会报丧的 Xcode Organizer

我们要承认,Xcode Organizer 确实提供了不少有用的情报:Crashes(崩溃)、Energy Impact(电量消耗)、Hangs(卡顿)、Launch Time(启动时间)、Memory Consumption(内存消耗)以及 App Terminations(App 终止)。

在这里插入图片描述

但是,它就像是那个只会在案发现场画白线的警察,对于某些棘手案件——特别是 App Terminations(App 莫名其妙被杀掉),它总是显得“智商捉急”。它能告诉你 App 挂了,但无法提供足够的细节来破案。

在这里插入图片描述

为了不让我们的 App 死不瞑目,Apple 上帝发了慈悲,赐予我们 MetricKit 框架。这玩意儿就像是法医手里的解剖刀,能让我们收集全面的诊断数据,构建一个详尽的“验尸报告”仪表盘。


🧱 第 2 幕:搭建秘密情报网

“要抓鬼,先得撒网。”王代码一边敲击键盘,一边嘟囔。

监控 App 性能的最直观方法,就是收集数据并将其导出以供分析。我们不能指望系统自动把凶手送到面前,我们得建立自己的 Analytics(分析)协议。

protocol Analytics {
    // 记录普通事件,比如“这破 App 又重启了”
    func logEvent(_ name: String, value: String)
    // 记录崩溃详情,这是法医鉴定的关键
    func logCrash(_ crash: MXCrashDiagnostic)
}

接下来,我们需要引入 MetricKit 并签署一份“灵魂契约”——设置订阅以接收数据。

在这里插入图片描述


🩸 第 3 幕:植入间谍(AppDelegate 集成)

王代码熟练地在 AppDelegate 中植入了监听器。这就像是在系统的血管里装了一个纳米机器人。

// 别忘了继承 MXMetricManagerSubscriber,这是入场券
final class AppDelegate: NSObject, UIApplicationDelegate, MXMetricManagerSubscriber {
    private var analytics: Analytics?

    func applicationDidFinishLaunching(_ application: UIApplication) {
        // 向组织(MXMetricManager)注册自己,有消息第一时间通知我
        MXMetricManager.shared.add(self)
    }

    // 重点来了:这是系统把“尸检报告”丢给你的时候
    // 注意:这个方法是非隔离的 (nonisolated),因为它可能在任意线程被调用
    nonisolated func didReceive(_ payloads: [MXMetricPayload]) {
        for payload in payloads {
            // 让我们看看它是怎么退出的... 
            // applicationExitMetrics 是关键证据
            if let exitMetrics = payload.applicationExitMetrics?.backgroundExitData {
                
                // 异常退出计数:是不是有什么不可告人的秘密?
                analytics?.logEvent(
                    "performance_abnormal_exit",
                    value: exitMetrics.cumulativeAbnormalExitCount.formatted()
                )
                
                // CPU 资源超限:是不是算力过载,脑子烧坏了?
                analytics?.logEvent(
                    "performance_cpu_exit",
                    value: exitMetrics.cumulativeCPUResourceLimitExitCount.formatted()
                )
                    
                // 内存压力退出:这就是传说中的“被系统嫌弃占地儿太大而清理门户”
                analytics?.logEvent(
                    "performance_memory_exit",
                    value: exitMetrics.cumulativeMemoryPressureExitCount.formatted()
                )
                
                // OOM(内存资源限制)退出:吃得太多,直接撑死
                analytics?.logEvent(
                    "performance_oom_exit",
                    value: exitMetrics.cumulativeMemoryResourceLimitExitCount.formatted()
                )
            }
        }
    }

    // 这里接收的是诊断信息,比上面的指标更硬核
    nonisolated func didReceive(_ payloads: [MXDiagnosticPayload]) {
        for payload in payloads {
            // 如果有崩溃诊断信息
            if let crashes = payload.crashDiagnostics {
                for crash in crashes {
                    // 把崩溃现场记录在案
                    analytics?.logCrash(crash)
                }
            }
        }
    }
}

“看到了吗,艾达?”王代码指着屏幕上的 applicationExitMetrics,“这才是我们要的真相。”

在这里插入图片描述

技术扩展说明: 如代码所示,我们利用 MXMetricManager 的共享实例来添加订阅者。我们的 AppDelegate 必须遵守 MXMetricManagerSubscriber 协议。这个协议提供了两个可选的“接收器”函数,让我们能够分别捕获 metrics(指标)和 diagnostics(诊断)。

在这里插入图片描述


💀 第 4 幕:解读死因(Payload 的奥秘)

艾达投影出一道蓝光,扫描着数据结构:“这两个 Payload 看起来很有料。”

MXMetricPayload 类型包含了一系列扩展自 MXMetric 抽象类的属性。其中最让王代码兴奋的是 applicationLaunchMetrics(应用启动指标)和 applicationExitMetrics(应用退出指标)。

在这里插入图片描述

在上面的代码中,王代码重点记录了几个引人注目的“后台终止”数据:

  • Cumulative Memory Pressure Exit Count:系统内存紧张时,你的 App 因为是个“显眼包”而被优先处决了。
  • Cumulative CPU Resource Limit Exit Count:你的 App 在后台偷偷挖矿或者死循环,耗尽了 CPU 配额,被系统当场击毙。

这些数据能让我们深刻理解——为什么系统觉得你的 App 不配活下去。

在这里插入图片描述

MXDiagnosticPayload 类型则包含扩展自抽象类 MXDiagnostic 的属性集合。例如 cpuExceptionDiagnostics(CPU 异常诊断)和 crashDiagnostics(崩溃诊断)。通过 logCrash 函数,我们能提取出极具价值的堆栈信息和元数据。

更妙的是,这两个 Payload 都能轻松转化为 JSONDictionary。这意味着我们可以毫不费力地把这些“罪证”上传到我们自定义的 API 端点,然后在后端慢慢审讯它们。

在这里插入图片描述


⏳ 第 5 幕:耐心的猎人

“现在我们只需要等待。”王代码靠在椅背上。

“等多久?现在的客户可没有耐心。”艾达提醒道。

“这是 MetricKit 的规矩。”王代码叹了口气。

关键点注意: MXMetricManager 并不会像喋喋不休的推销员一样实时给你推送数据。系统非常“鸡贼”,为了省电和性能,它会把数据聚合起来,通常按每天一次的频率投递。

在这里插入图片描述

也就是说,你今天埋下的雷,可能明天才能听到响。在极少数情况下,它可能会发得频繁点,但你千万别把身家性命压在这个“特定时间表”上。

不过好在,这两个 Payload 都提供了 timeStampBegintimeStampEnd 属性。这就好比尸检报告上的死亡时间推断,让我们能精准地确定这些数据覆盖的时间范围。


🎬 终章:真相大白

窗外的雨停了,新深圳的霓虹灯映在王代码疲惫但兴奋的脸上。

通过 MetricKit,他终于填补了 Xcode Organizer 留下的巨大空白。这不仅仅是看几个数字那么简单,这是对 App 在真实世界(Real-World Conditions)中行为的系统级洞察。

在这里插入图片描述

通过订阅 MXMetricManager 并处理 MXMetricPayloadMXDiagnosticPayload,王代码获得了关于 App 启动、终止、崩溃和资源使用的“上帝视角”。而在过去,想要搞清楚 App 是怎么在后台悄无声息死掉的,简直比让产品经理承认需求不合理还难。

“案子破了,艾达。”王代码站起身,披上风衣,“是内存泄漏导致的 OOM,凶手就在那个循环引用的闭包里。”

在这里插入图片描述

艾达关掉了全息投影,嘴角露出一丝不易察觉的微笑:“干得不错,老王。但别高兴得太早,下周还有新的 Bug 等着你。”

在这里插入图片描述

感谢阅读这篇来自赛博边缘的性能监控指南。如果你觉得这次冒险有点意思,或者对抓 Bug 有什么独到的见解,欢迎关注我的博客并向我提问。

咱们下周见,祝宝子们的代码永远不做“内存刺客”,棒棒哒!👋

在这里插入图片描述

一款轻量、低侵入的 iOS 新手引导组件,虽然大清都亡了

PolarisGuideKit:轻量、低侵入的 iOS 新手引导组件(遮罩挖孔 + Buddy View + 插件化)

关键词:UIKit · 新手引导 · 低侵入 · 插件扩展

GitHub:github.com/noodles1024…

demo_cn_tiny.webp


背景:我为什么做这个组件?

可能是新手引导这个功能太小,随便实现一下也能用,导致没有人愿意认真写一个iOS下的新手引导组件,搜遍整个github也找不到一个在现实项目中能直接拿来用的。如果只考虑某一个具体的新手引导界面,实现起来很容易(特别是现在在AI的加持下,UI仔都不需要了)。但在不同项目、不同场景下,经过和和产品经理&设计师的多次沟通中,我发现了做“新手引导/功能提示”时的一些令人头疼的问题:

  • 需要高亮某个控件,但布局变化、屏幕旋转后挖孔(高亮)位置容易偏
  • 指引说明(箭头/气泡/按钮)形态不固定,可能还伴随着音频播放等附加功能,复用困难
  • 点击高亮区域时,难以做到不侵入原有点击业务逻辑
  • 显示新手引导时难以在不改变原有逻辑的情况下阻止NavigationController的滑动返回
  • UITableView/UICollectionView reloadData 后高亮经常失效

于是我做了 PolarisGuideKit:一个基于 UIKit 的轻量新手引导组件,主打低侵入 + 可扩展 + 动态高亮


PolarisGuideKit 能解决什么?

能力 说明 带来的价值
高亮遮罩 遮罩挖孔高亮 focusView 高亮区域自动跟随,内置高亮效果,可自定义
Buddy View 说明视图可自由定制 文案、箭头、按钮任意组合
步骤编排 多步骤引导流程 支持下一步、跳过、完成
动态 focusView reloadData 后自动修正 TableView/CollectionView场景稳定
插件化扩展 Audio/埋点/持久化 可插拔、解耦

快速上手(3 分钟接入)

import UIKit
import PolarisGuideKit

final class MyViewController: UIViewController {
    private var guide: GuideController?

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)

        let step = GuideStep()
        step.focusView = myButton
        step.buddyView = MyBuddyView()
        step.forwardsTouchEventsToFocusView = true
        step.completer = ControlEventCompleter(control: myButton, event: .touchUpInside)

        let controller = GuideController(hostView: view, steps: [step])
        controller.onDismiss = { _, context in
            print("引导结束,原因 = \(context.reason)")
        }

        _ = controller.show()
        guide = controller
    }
}

核心概念一图速览

  • GuideController:流程编排器,负责 show/hide/切换步骤
  • GuideStep:一步引导配置(focus、buddy、style、completer)
  • FocusStyle:高亮形状(矩形/圆形/圆角/无高亮)
  • GuideBuddyView:说明视图(可继承自定义)
  • GuidePlugin:生命周期扩展(音频/埋点/持久化)

重点能力拆解

1) FocusStyle:高亮样式可拔插

内置样式包含:

  • DefaultFocusStyle(矩形)
  • RoundedRectFocusStyle(圆角矩形)
  • CircleFocusStyle(圆形)
  • NoHighlightFocusStyle(全屏遮罩)
let step = GuideStep()
step.focusView = someCard
step.focusStyle = RoundedRectFocusStyle(
    focusCornerRadius: .followFocusView(delta: 2),
    focusAreaInsets: UIEdgeInsets(top: -6, left: -6, bottom: -6, right: -6)
)

2) 动态 FocusView:Table/CollectionView不卡壳

UITableView / UICollectionView 复用导致高亮错位?
使用 focusViewProvider 动态获取最新 cell:

let step = GuideStep()
step.focusViewProvider = { [weak self] in
    guard let self else { return nil }
    var cell = self.tableView.cellForRow(at: targetIndexPath)
    if cell == nil {
        self.tableView.layoutIfNeeded()
        cell = self.tableView.cellForRow(at: targetIndexPath)
    }
    return cell
}

3) 触摸转发 + 自动完成

在不侵入原有业务逻辑的前提下,高亮按钮依然能触发业务逻辑,同时自动关闭引导:

let step = GuideStep()
step.focusView = myButton
step.forwardsTouchEventsToFocusView = true
step.completer = ControlEventCompleter(control: myButton, event: .touchUpInside)

✅ 设置forwardsTouchEventsToFocusView和completer保证了“引导不侵入原有业务逻辑”。


4) Buddy View:说明视图随便做

继承 GuideBuddyView,自定义 UI + 布局:

final class MyBuddyView: GuideBuddyView {
    override func updateLayout(referenceLayoutGuide layoutGuide: UILayoutGuide, focusView: UIView) {
        super.updateLayout(referenceLayoutGuide: layoutGuide, focusView: focusView)
        // 根据 layoutGuide 布局你的文案 / 按钮 / 箭头
    }
}

5) 插件系统:音频 / 埋点 / 持久化

内置 AudioGuidePlugin,可在显示引导时播放音频文件,且可在BuddyView中配合显示音频播放动画(可选功能):

let step = GuideStep()
step.focusView = myCard
step.addAttachment(GuideAudioAttachment(url: audioURL, volume: 0.8))

let controller = GuideController(
    hostView: view,
    steps: [step],
    plugins: [AudioGuidePlugin()]
)

如果想要加埋点、标记“引导是否已显示”,可通过自定义 GuidePlugin 实现。


Demo 示例一览

  • 圆角矩形高亮 + 圆角模式切换
  • 圆形高亮 + 半径缩放
  • 多步骤引导 + 平滑转场
  • 触摸转发 + 自动完成
  • 点击外部关闭(dismissesOnOutsideTap)
  • 音频 + Lottie 同步演示
  • UITableView 动态高亮

架构 & 视图层级

flowchart TB
    subgraph Core["核心组件"]
        GuideController["GuideController<br/>(流程编排器)"]
        GuideStep["GuideStep<br/>(步骤配置)"]
    end

    subgraph ViewHierarchy["视图层级"]
        GuideContainerView["GuideContainerView<br/>(透明容器)"]
        GuideOverlayView["GuideOverlayView<br/>(遮罩 + 触摸转发)"]
        MaskOverlayView["MaskOverlayView<br/>(遮罩基类)"]
        GuideBuddyView["GuideBuddyView<br/>(说明视图)"]
        GuideShadowView["GuideShadowView<br/>(焦点追踪器)"]
    end

    subgraph Extensions["扩展机制"]
        FocusStyle["FocusStyle<br/>(高亮形状)"]
        GuideAutoCompleter["GuideAutoCompleter<br/>(完成触发器)"]
        GuidePlugin["GuidePlugin<br/>(生命周期钩子)"]
        GuideStepAttachment["GuideStepAttachment<br/>(插件数据)"]
    end

    GuideController -->|"管理"| GuideStep
    GuideController -->|"创建并承载"| GuideContainerView
    GuideController -->|"派发事件"| GuidePlugin
    
    GuideContainerView -->|"包含"| GuideOverlayView
    GuideContainerView -->|"包含"| GuideBuddyView
    
    GuideOverlayView -.->|"继承"| MaskOverlayView
    GuideOverlayView -->|"创建"| GuideShadowView
    GuideOverlayView -->|"使用"| FocusStyle
    
    GuideStep -->|"配置"| GuideBuddyView
    GuideStep -->|"使用"| FocusStyle
    GuideStep -->|"通过...触发"| GuideAutoCompleter
    GuideStep -->|"携带"| GuideStepAttachment

view_hierarchy.png


安装

Swift Package Manager

  1. Xcode → File → Add Packages…
  2. 输入仓库地址:https://github.com/noodles1024/PolarisGuideKit
  3. 选择 PolarisGuideKit

CocoaPods

pod 'PolarisGuideKit'
import PolarisGuideKit

注意事项(踩坑清单)

  • focusView 必须是 hostView 的子视图
  • 多 Scene / 多 Window 建议显式传 hostView
  • GuideAutoCompleter 触发后会结束整个引导(建议用于最后一步)
  • 动画转场在复杂形状下可关闭动画:animatesStepTransition = false

项目地址 & 交流

AT 的人生未必比 MT 更好 -- 肘子的 Swift 周报 #118

issue118.webp

AT 的人生未必比 MT 更好

学车时我开的是手动挡,起初因为技术生疏,常搞得手忙脚乱,所以第一台车就直接选了自动挡。但开了几年,我开始追求那种完全掌控的驾驶感,于是又增购了一台手动挡。遗憾的是,随着交通日益拥堵,换挡的乐趣逐渐被疲惫抵消,最终这台车也被冷落。算起来,我已经快二十年没认真开过手动挡了,但内心深处,我仍会时不时地怀念那段“人车合一”的时光。

随着 AI 深度介入我的工作与生活,我感觉自己的人生正从 MT 转向 AT。毫无疑问,AI 助我突破了许多能力瓶颈,也在熟悉领域带来了巨大的效率提升。但奇怪的是,我对它的“惊叹”却在与日俱减。看似它节省了我的时间,但我并未从这些“多出来的时间”里获得预期的满足感。也许是我对它的期望阈值不断提高,但一个不争的事实是:我已经有一段时间没有在学习和开发过程中,体会到那种单纯的快乐了。

幸好,几天前我又找回了这种久违的开心。在准备 iOS Conf SG 的 Keynote 时,由于 Keynote 在动画构建上相对“原始”且缺乏 AI 辅助,我难得地拥有一段完整的时间,去纯手工地尝试和修改。哪怕只是一个简单的并行动画,究竟是用转场、普通动画还是“神奇移动”,我都玩得不亦乐乎。那些在专家手里可能两三分钟搞定的设置,我折腾了大半天。尽管毫无效率可言,但我乐在其中。看着最终那个略显“简陋”的效果,我竟被自己感动了。

对于职场中人,效率和完成度固然是硬指标;但能否体会到过程带来的“实感”,或许才是作为“人”最朴素的追求。

我大概率不会再买 MT 的车了,但在我还能握紧方向盘的时候,也不会轻易让“智能驾驶”代劳。写代码也是如此,当初爱上它,正是因为它能给我带来纯粹的快乐。当所有工具都在催促我们变得更快更好时,我想应该给自己留一点变慢、变“笨”的空间——毕竟,AT 的人生未必比 MT 更好。

本期内容 | 前一期内容 | 全部周报列表

🚀 《肘子的 Swift 周报》

每周为你精选最值得关注的 Swift、SwiftUI 技术动态

近期推荐

告别“可移植汇编”:我已让 Swift 在 MCU 上运行七年

从 2024 年开始,Swift 官方正式提供了对嵌入式系统的支持,但要在这个领域获得显著份额,仍有很长的路要走。其实,早在官方下场之前的 2018 年,Andy Liu 和他的 MadMachine 团队就开始在探索和实践将 Swift 应用于嵌入式领域,并陆续推出了相关硬件。他们坚信,在功能日益复杂的开发场景中,Swift 的现代语言特性将展现出巨大的优势。在本文中,Andy 分享了过去几年中在该领域的探索历程。我真心希望,Swift 能够在更多的场景中,展现其魅力。


在 SwiftUI 中构建基础拨号滑块组件 (Building a Base DialSlider Component in SwiftUI)

在 AI 功能越来越强大的今天,看到一个动效,让 AI 帮你实现已经越来越容易了。但每当看到开发者凭借自己的"奇思妙想"不断探索实现方式并打磨效果时,我仍会由衷赞叹。codelaby 在这篇复刻"老式电话拨号盘"的文章中,巧妙运用 SwiftUI 的 .compositingGroup().blendMode(.destinationOut) 实现了动态"镂空"效果,使旋转层下的静态数字清晰显现,相比单纯旋转图片更具灵活性和原生质感。此外,文章对环形手势处理、角度计算(atan2)以及限位逻辑(Stopper)的阐述也十分透彻清晰。


CKSyncEngine 答疑与实战经验分享 (CKSyncEngine Questions and Answers)

不少开发者对 Core Data 的 NSPersistentCloudKitContainer 颇有诟病,认为其不透明且缺乏定制性。但真正想自己着手解决 CloudKit 的数据同步问题时,才发现需要考虑的地方实在太多,难度远超想象。苹果在几年前推出的 CKSyncEngine 彻底打破了这个困境,提供了更清晰的状态管理和错误处理,并自动处理了诸多复杂的边缘情况,让开发者可以专心构建数据同步逻辑。

Christian Selig 通过自问自答的方式,分享了他在使用 CKSyncEngine API 时的经验,详细拆解了 CKSyncEngine 如何作为一个完美的中间层,在保留数据存储灵活性(你可以继续用 SQLite、Realm 或 JSON)的同时,接管了最令人头疼的同步状态管理。


我对 iOS 26 Tab Bar 的吐槽 (My Beef with the iOS 26 Tab Bar)

SwiftUI 在 iOS 18 中对 Tab Bar 的调整,其影响几乎堪比当年 NavigationStack/NavigationSplitView 取代 NavigationView,不仅改变了设计语言,对应用的实现方式和数据流走向都产生了颠覆性影响。而为 iOS 26 Liquid Glass 风格引入的"搜索标签"功能进一步推进了这种变革。Ryan Ashcraft 在这篇文章中直言不讳地指出了新 Tab Bar 设计的诸多问题:默认的浮动样式在某些界面中显得突兀,与应用整体视觉风格难以协调;新的边距和间距规则打破了长期以来的设计惯例,让开发者需要重新调整大量现有界面;更重要的是,这些改动并未明显提升用户体验,反而增加了适配成本。

我个人对新 Tab 的最大感受是,它会显著影响开发者在开发应用时对最低系统版本的决策。为 Tab 维护两套代码是否值得?如果为了简化实现而不得不将最低版本提高到 iOS 18,这或许正是 SwiftUI 团队的另一个设计意图?


Dia:深度剖析 The Browser Company 的 macOS 浏览器架构 (Dia: A Technical Deep Dive into The Browser Company's macOS Browser)

Arc 是第一个使用 Swift 构建的大型 Windows 平台应用,而且 The Browser Company 也因此为 Swift 社区的 Windows 工具链做出了突出贡献。在从 Arc 转型到 Dia 后,开发团队并没有放弃使用 Swift,那么 macOS 端的 Dia 具体使用了哪些开发框架呢?

Everett 在本文中揭示了 Dia 独特的技术架构:这是一个基于 AppKit + SwiftUI 的原生 macOS 应用,但其核心渲染引擎并非 WebKit,而是嵌入了自行修改的 Chromium(ArcCore)。此外,在 Dia 的二进制文件中发现了大量与本地 AI 相关的库(如 Apple MLX 和 LoRA 适配器),这预示着 Dia 并非只是为了"快",而是已经为设备端 AI 推理做好了底层工程准备。


关于罗技开发者证书过期的迷思 (Myths about Logitech Developer ID certificate expiration)

几天前,不少 macOS 用户发现罗技鼠标的自定义按钮失效。由于控制台日志中充斥着代码签名(Code Signing)相关的报错,不少用户和媒体将其归咎于"苹果撤销了证书"。Jeff Johnson 通过分析系统日志为苹果在本次事件中的角色进行了平反:这并非苹果的证书服务故障,而是罗技自身软件工程问题导致的。Logi Options+ 的后台进程在更新后,未能通过 macOS taskgated 的代码签名有效性验证,从而被系统直接终止。这篇文章不仅是一份故障分析报告,更提醒开发者:在 macOS 严格的安全机制下,应用更新的签名验证流程容不得半点马虎。

“如果你的证书过期了,用户仍然可以下载、安装和运行用该证书签名的 Mac 应用程序版本。但是,你需要一个新的证书来签署更新和新申请。” —— 苹果官方文档


拒绝 LLM 生成的平庸代码 (Stop Getting Average Code from Your LLM)

不可否认,在人类长久以来累积的信息海洋中,高质量的数据与信息只占少数。对于个体来说,我们完全可以有目的地去甄别和学习这些优质内容。但是,受限于机制,LLM 默认倾向于训练数据的“平均值”,这就导致它生成的内容在各个方面都显得比较平庸。具体到 Swift 开发领域,这往往意味着它会生成大量旧版的、非结构化的代码。

要想获得高质量、符合 Swift 6 标准甚至特定架构风格的代码,关键在于对抗这种“回归均值”的本能。Krzysztof Zabłocki 详细介绍了如何利用 Few-Shot Prompting(少样本提示)和上下文注入技术,通过提供具体的代码范例和架构规范,强迫 LLM “忘记”平庸的默认设置,转而生成精准匹配项目标准的高质量代码。

工具

swift-effect: 一种基于类型驱动的副作用处理方案

Alex Ozun 长期关注 Swift 中的 类型驱动设计,这个库是他对“代数效应(Algebraic Effects)+ 处理器(Effect Handlers)”在 Swift 里的实践。 swift-effect 不是把副作用变成“数据结构再解释”,而是将副作用建模为可拦截的全局操作(@Effect),通过 handler 在运行时组合和替换行为,让业务代码保持线性/过程式风格,同时又能精细控制 I/O、并发等行为。

核心亮点:

  • 保持代码线性:调用 Console.print 等 effect 就像普通函数,但行为可由 handler 动态决定。
  • 无 Mock 的行为测试:用 withTestHandler 逐步拦截/断言 effect 序列,像“交互式脚本”一样测试流程。
  • 并发可控:支持对 Task/AsyncSequence 的确定性测试,解决并发顺序不稳定的问题。

Codex Skill Manager: 一款面向众多 CLI 的 macOS 工具

很多开发者都会同时使用多种 AI 编程服务,尽管它们拥有类似的概念、设定和工具类型,但在具体设置和细节描述上仍有差异,这导致开发者很难对所有服务进行统一管理。Thomas Ricouard 开发的 Codex Skill Manager 将 Codex、Claude Code(以及 OpenCode、Copilot)的技能集中在一个 UI 里查看、搜索、删除和导入,避免在多个隐藏目录中手动寻找。

核心功能

  • 本地技能:扫描 ~/.codex/skills/public~/.claude/skills 等路径,展示列表与详情
  • 详情渲染:Markdown 视图+引用预览
  • 远程 Skill:Clawdhub 搜索/最新列表、详情拉取与下载
  • 导入/删除/自定义路径:支持从 zip 或文件夹导入、侧边栏删除、添加自定义路径
  • 多平台安装状态:为不同平台标记已安装状态

活动

LET'S VISION 2026|邀请你与我们同行!

✨ 大会主题:Born to Create, Powered by AI

  • 📍 地点:上海漕河泾会议中心
  • 时间:2026 年 3 月 27 日 - 3 月 29 日
  • 🏁 重点:汇聚顶尖创作者与 AI 技术大咖,共同探索 AI 应用的未来边界
  • 🌍 官网letsvision.swiftgg.team

别走开!请关注官方账号和主理人 SwiftSIQI,我们将持续放送更多精彩内容!


Swift Student Challenge 2026

每年一度的学生挑战赛再次登场。挑战赛为数以千计的学生开发者提供了展现创造力和编程能力的机会,让他们可以通过 App Playground 呈现自己的作品,并从中学习在职业生涯中受用的实际技能。

今年作品提交通道将于 2026 年 2 月 6 日至 2 月 28 日开放。

往期内容

💝 支持与反馈

如果本期周报对你有帮助,请:

  • 👍 点赞 - 让更多开发者看到
  • 💬 评论 - 分享你的看法或问题
  • 🔄 转发 - 帮助同行共同成长

🚀 拓展 Swift 视野

iOS日志系统设计

1 为什么需要日志

软件系统的运行过程本质上是不可见的。绝大多数行为发生在内存与线程之中。在本机调试阶段,我们可以借助断点、内存分析、控制台等手段直接观察系统状态;而一旦进入生产环境,这些能力几乎全部失效。此时,日志成为唯一能够跨越时间和空间的观测手段

但如果进一步追问:日志究竟解决了什么问题? 这个问题并没有那么简单。日志的核心价值并不在于文本本身,而在于可见性。它最基础的作用,是让这些不可见的行为“显影”。一次简单的日志输出,至少隐含了三类信息:时间、位置、描述。

这也是我们不建议使用简单 print 的原因:结构化日志在每次记录时,都会自动携带这些关键信息,从而形成稳定、可检索的观测数据。

之后当系统规模变大、异步逻辑增多时,单条日志已经很难解释问题。真正有价值的,是一组日志所呈现出的因果关系. 在这一层面上,日志更像是事件证据,用于在事后还原一段已经发生过的执行流程。

接下来,我们将从这些问题出发,逐步讨论一套面向真实生产环境的日志与可观测性设计。

2 日志系统

尽管日志在实践中无处不在,它本身仍然存在天然局限:日志是离散的事件,而不是连续的流程;日志天然是“事后信息”,而不是实时状态;在客户端等受限环境中, 如 应用可能随时被杀掉, 各种网络情况不稳定, 隐私与安全限制,日志可能丢失、不可获取、不可上报。

这意味着,日志并不是系统真相本身,它只是我们理解系统的一种工具。当系统复杂度继续提升,仅靠“多打日志”往往无法解决根本问题。

2.1 范围与功能

这样我们应该勾勒出日志系统的一些边界范围.

  1. 不必要求日志的「绝对可靠上报」
  2. 不通过日志修复「系统设计问题」(业务依赖、生命周期、指责转移错误)
  3. 不将日志系统演化成「消息系统」(不持久化、不通过日志兜底)

所以我们通过边界范围基本确定了我们日志系统的一些要求:

  • 结构化并非文本化: 日志首先应该是结构化数据,而不是简单字符串。文本只是表现形式,结构才是核心价值.每条日志必须具备稳定的时间、位置、级别与上下文.日志应当天然支持检索、过滤与关联.
  • 本地优先, 而非远端依赖: 本地记录必须是同步、低成本、稳定的.远端上报只能是 best-effort 行为.系统不能因为远端日志失败而影响主流程

2.2 系统架构

LoggerSystemArchitectureDiagram.svg

我们刻意限制了日志系统的职责范围,使其始终作为一个旁路的、可退化的基础设施存在。这些约束并非功能缺失,而是后续实现能够保持稳定与可演进的前提。所有依赖关系均为单向:日志系统不会反向调用业务模块或基础设施。

3 本地日志

在整体架构中,本地日志被视为整个日志系统中最基础、也是最可靠的一环。无论远端日志是否可用、网络环境是否稳定,本地日志都必须能够在任何情况下正常工作。

因此,在实现层面,我们选择优先构建一套稳定、低成本、符合平台特性的本地日志能力,而不是从远端导出反推本地设计。

3.1 为什么是os.Logger

在 iOS 开发里,print 很直观,但它更像调试手段:没有结构、难以检索、性能成本不可预测,也无法进入系统日志体系。进入生产环境后,这些缺点会被放大。

os.Logger 是系统级日志通道,它的设计目标本身就面向“可长期运行”的生产场景。本文中,os.Logger 指 Apple 的系统日志实现,Logger 指本文封装的对外 API。我们选择它,主要基于这些原因:

  • 低成本写入:日志被拆分为静态模板与动态参数,格式化发生在读取阶段,而非写入阶段
  • 系统工具链一致性:天然接入 Console、Instruments 与系统日志采集工具
  • 隐私与合规能力:原生支持隐私级别控制
  • 结构化上下文:时间戳、级别、分类、源码位置可以稳定保留

因此,日志可以作为“长期存在的基础能力”,在核心路径中持续开启,而不是仅限于调试阶段。需要说明的是,系统日志在生产环境的获取也受平台权限与采集策略限制,所以它是“本地可靠”,但并不是“远端万能”。

在使用层面,Logger API 保持简单直接:

let logger = Logger(subsystem: "LoggerSystem")
logger.info("Request started")
logger.error("Request failed", error: error)

3.2 附加功能

除了系统日志的即时写入,我们还提供了几个本地诊断能力:通过 LogStore / OSLogStore 进行日志检索(按时间、级别、分类)并支持导出为文本或 JSON;同时集成 OSSignpost / OSSignposter 作为性能事件记录方式,用于衡量关键路径耗时。这些能力不进入主写入路径,只在排查与分析时启用。

4 远端日志与 OpenTelemetry

4.1 OpenTelemetry 在客户端日志系统中的位置

OpenTelemetry 由 CNCF 托管,起源于 2019 年 OpenCensus 与 OpenTracing 的合并,并于 2021 年成为 CNCF 顶级项目。它并不是某一个具体 SDK,而是一套用于描述可观测性数据的开放标准,定义了日志、指标与链路追踪的统一语义与数据模型,并配套给出了标准化的传输协议(OTLP)。

在本章中,我们并不试图完整覆盖 OpenTelemetry 的体系,而是聚焦于其中与远端日志相关的部分:

日志数据在 OTel 语义下如何被结构化、如何被分组、以及如何被导出。

认证、上下文传播等问题会显著影响系统依赖关系,本文刻意将其延后,在下一章单独讨论。

4.1.1 Remote Logger 的最小闭环

下图展示了在 OTel 语义下,客户端远端日志链路的最小可用闭环

这一闭环的目标并非“可靠投递”,而是在客户端约束条件下,提供一条可控、可退化的日志导出路径

从数据流动的角度看,这条链路可以被抽象为:

LogRecord[]
  → LogRecordAdapter
  → ResourceLogs / ScopeLogs / LogRecords
  → ExportLogsServiceRequest (OTLP)
  → OTLP Exporter (HTTP / gRPC)

在这一结构之上,可以按需叠加增强能力,例如批处理、失败缓存或延迟调度,但这些能力不会改变日志的协议语义

4.1.2 结构化与分组:从 LogRecord 到 OTel Logs

在 OTel 模型中,LogRecord 仍然是最小的事件单元,用于描述“发生了什么”。

但真正的上传结构并不是一组扁平的日志列表,而是按以下层级组织:

  • ResourceLogs:描述日志产生的资源环境(设备、系统、应用)
  • ScopeLogs:描述产生日志的逻辑作用域(模块、库)
  • LogRecords:具体的日志事件

这一分组方式的意义在于:

  • 避免重复携带环境信息
  • 明确日志的来源与归属
  • 为后端聚合与分析提供稳定结构

在客户端侧,这一阶段通常通过一个 Adapter 或 Mapper 完成,其职责只是语义映射,而非业务处理。

4.1.3 批处理与调度:Processor 的职责边界

在日志被结构化之后,下一步并不是立刻发送,而是进入处理阶段。

LogRecordProcessor 位于这一阶段的入口位置。以 BatchLogRecordProcessor 为例,它负责:

  • 将多条日志聚合为批次
  • 控制发送频率
  • 降低网络与系统调用成本

需要注意的是,Processor 层体现的是策略位置,而不是协议逻辑。

它不关心日志如何被编码,也不关心最终通过何种方式发送,只负责决定什么时候值得尝试导出

4.1.4 导出边界:Exporter 作为协议适配层

LogRecordExporter 是远端日志链路中的协议边界

在这一层中,结构化日志会被转换为 OTLP 定义的 ExportLogsServiceRequest,并通过具体传输方式发送。常见实现包括:

  • OTLP/HTTP
  • OTLP/gRPC

无论采用哪种方式,Exporter 的核心职责都是一致的:

编码日志结构,并完成协议级发送。

它不感知业务上下文,也不参与重试策略之外的系统决策。

4.2 RemoteLogger 架构图

下面这张图是 RemoteLogger 在 OTel 语义下的最小闭环:

RemoteSinkSystem.svg

5 上下文边界

从 RemoteLogger 开始真正发日志的那一刻,日志系统就第一次碰到外部依赖:鉴权。它不是“可选附加项”,而是远端链路的必经之门。

5.1 鉴权

日志端点是基础设施入口(infra endpoint),它的目标是控制写入来源,而不是验证用户身份。因此更合理的鉴权方式是:IP allowlist、mTLS、ingestion key、project‑level key,配合采样与限流。这些机制与用户态解耦、无需刷新、不参与业务控制流,且失败也不会影响客户端主流程。

在这种模型下,日志系统只做一件事:携带已准备好的凭证。它不维护鉴权状态,也不触发刷新,更不等待鉴权完成。

5.1.1 当鉴权被卷入业务流程

问题发生在日志复用业务鉴权体系时:access token 短期、频繁刷新、刷新依赖网络与生命周期,而鉴权失败本身又需要被记录。直觉做法是“刷新后重试”,但这会形成典型的依赖循环:

Logger
  → RemoteExporter
     → AuthManager
        → RefreshToken
           → Network
              → Logger

这不是实现复杂的问题,而是依赖方向错误的问题:日志系统依赖了本应被它观测的系统,直接造成 auth blind zone(鉴权失败本身无法被观测的区域)

现实里,很多团队不得不复用业务鉴权,但这时唯一能做的是“隔离副作用”:不触发刷新、不重试鉴权、失败即丢弃,并保持凭证只读与短生命周期缓存。这样做无法消灭问题,却能把依赖循环缩到最小。

结论只有一句:日志系统只能消费鉴权结果,不能成为鉴权流程的一部分。

5.2 Traceparent

traceparent 是 W3C Trace Context 标准里的核心头部,用于跨进程传播 Trace。它不是日志系统的一部分,而是“流程上下文”的载体。日志系统只负责把它携带出去,而不负责生成、维护或推进它。

它的基本结构非常固定:

traceparent: {version}-{trace-id}-{parent-id}-{trace-flags}
  • version:版本号,当前常见为 00
  • trace-id:16 字节(32 hex)的全局 trace 标识
  • parent-id:8 字节(16 hex)的当前 span 标识
  • trace-flags:采样与调试标记(如 01 表示采样)

这四个字段共同决定“这条日志属于哪条 trace、处于哪一段 span 上下文”。

5.2.1 构造与传递

在客户端日志系统中,traceparent 应当被视为外部上下文

  • 它由业务流程或 tracing 系统生成
  • 它随着请求/事件生命周期变化
  • 它不由日志系统创建,也不由日志系统维护

日志系统只做一件事:在日志生成或导出时附带 traceparent,让后端能够把日志与 Trace 对齐。

这也意味着:日志系统不能尝试“修复” traceparent,也不能在缺失时伪造它。缺失就缺失,伪造会制造错误的因果链。

traceparent 的构造来自 tracing 系统(SDK 或上游服务),它会在一次请求开始时生成新的 trace-id,并在 span 变化时更新 parent-id。日志系统只需在“生成日志的瞬间”读取当前上下文并携带即可。

换句话说,traceparent 的生命周期与日志系统无关,而与业务流程一致。日志系统需要尊重这个边界,否则它会再次变成主流程的一部分。

5.3 Context 的角色

如果说 traceparent 是“具体的上下文载体”,那么 Context 是“上下文在系统里的容器与作用域”。它回答的不是“字段长什么样”,而是“这份上下文从哪来、到哪去、何时结束”。

在日志系统里,Context 只应当承担两件事:

  1. 携带流程信息,让日志具备可关联性
  2. 限定生命周期,避免上下文在系统内滞留

这意味着 Context 的设计重点不是“存什么”,而是“何时注入、如何传播、何时释放”。

更宽泛地看,Context 的生命周期其实是一种“作用域建模”。它既像 tracing 里的 active span,也像 DI 里的 scope:谁负责创建、谁负责结束、跨线程如何继承,这些都会直接决定 traceparent 的 parent-id 何时变化。换句话说,Context 的问题往往不是协议问题,而是作用域与生命周期策略的问题。

Context 最难的部分其实是作用域与注入方式:

  • 它和依赖注入(DI)的关系应该是什么
  • 在多线程/异步场景中,Context 的边界如何定义
  • Context 是否应该是显式传参,还是隐式绑定

这些问题没有一个完美答案,需要团队给出清晰的工程约定。

5.4 结语

这套日志系统的核心不是“更多日志”,而是“正确的边界”:本地优先、远端旁路、结构化可关联、上下文可控。真正决定系统稳定性的,不是某一个 API,而是你如何定义依赖方向与生命周期。最后想留下的一句话是:可观测性不是无限的,它永远受平台约束。

深入理解 Swift Concurrency:从 async/await 到隔离域

在 Swift 并发系统(Swift Concurrency)诞生之前,iOS 开发者的日常被回调(Callbacks)、代理(Delegates)和 Combine 填满。我们用这些工具来处理应用中大量的等待时间:网络请求、磁盘 I/O、数据库查询。它们虽然能解决问题,但代价是代码的可读性——嵌套的回调地狱(Callback Hell)和陡峭的 Combine 学习曲线让代码维护变得艰难。

Swift 的 async/await 引入了一种全新的范式。它允许开发者用看似同步的顺序代码来编写异步逻辑。底层运行时高效地管理着任务的暂停与恢复,而不再需要开发者手动在回调中穿梭。

但 async/await 只是冰山一角。Swift 并发模型的真正核心,在于它如何从根本上改变了我们对“线程安全”的理解——从管理线程(Threads)转向管理隔离(Isolation)。

本文将深入探讨这一体系,从基础语法到隔离域模型,再到实际开发中的最佳实践。

基础:暂停与恢复

异步函数(Async Function)  是这一模型的基础构建块。通过 async 标记,函数声明了它具有被“挂起”的能力。在调用时,await 关键字则是一个明确的标记,表示“在此处暂停,直到任务完成”。

func fetchUser(id: Intasync throws -> User {
    let url = URL(string"https://api.example.com/users/(id)")!
    // 执行权在此处交出,当前函数挂起
    let (data, _) = try await URLSession.shared.data(from: url)
    return try JSONDecoder().decode(User.self, from: data)
}

// 调用示例
let user = try await fetchUser(id: 123)
// fetchUser 完成后,代码才继续向下执行

这里的关键在于 挂起(Suspension)  而非 阻塞(Blocking) 。当代码在 await 处暂停时,当前线程并不会被锁死,Swift 运行时会利用这段空闲时间去处理其他工作。当异步操作完成,函数会从暂停的地方恢复执行。

并行:结构化并发

顺序执行 await 虽然直观,但在处理多个独立任务时效率低下。如果我们需要同时获取头像、横幅和简介,逐个等待会导致不必要的串行延迟。

async let 允许我们以声明式的方式并行启动任务:

func loadProfile() async throws -> Profile {
    // 三个任务立即同时启动
    async let avatar = fetchImage("avatar.jpg")
    async let banner = fetchImage("banner.jpg")
    async let bio = fetchBio()

    // 在需要结果时才进行 await
    return Profile(
        avatar: try await avatar,
        banner: try await banner,
        bio: try await bio
    )
}

这种方式既保留了代码的整洁,又实现了并行的高效。

如果任务数量是动态的(例如下载一个数组中的所有图片),则应使用 TaskGroup。它将任务组织成树状结构,父任务会等待组内所有子任务完成或抛出错误。这种层级关系被称为 结构化并发(Structured Concurrency) ,其最大优势在于生命周期管理:取消父任务会自动传播给所有子任务,且错误处理更加可预测。

任务管理:Task 的正确用法

编写了异步函数后,我们需要一个上下文来运行它们。Task 就是这个异步工作单元。它提供了从同步代码进入异步世界的桥梁。

视图层面的管理

在 SwiftUI 中,最推荐的方式是使用 .task 修饰符。它自动管理任务的生命周期:视图显示时启动,消失时自动取消。

struct ProfileViewView {
    var userIDString
    @State private var avatarImage?

    var body: some View {
        // 当 userID 变化时,旧任务取消,新任务启动
        Image(systemName"person")
            .task(id: userID) {
                avatar = await downloadAvatar(for: userID)
            }
    }
}

常见的反模式:不受管理的 Task

开发者常犯的一个错误是滥用 Task { ... } 或 Task.detached { ... }。这种手动创建的任务是“非托管”的。一旦创建,你就失去了对它的控制权:无法自动随视图销毁而取消,难以追踪执行状态,也难以捕获其中的错误。

这就像把漂流瓶扔进大海,你不知道它何时到达,也无法在发出去后撤回。

最佳实践

    1. 优先使用 .task 修饰符或 TaskGroup
    1. 仅在确实需要(如点击按钮触发)时使用 Task { },并意识到其生命周期的独立性。
    1. 极少使用 Task.detached,除非你明确知道该任务不需要继承当前的上下文(如优先级、Actor 隔离)。

核心范式转变:从线程到隔离

在 Swift 并发出现之前,不管是 GCD 还是 OperationQueue,我们关注的核心是 线程(Thread) :代码在哪个队列跑?是否在主线程更新 UI?

这种模型极其依赖开发者的自觉性。一旦忘记切换线程,或者两个线程同时访问同一块内存,就会导致 数据竞争(Data Race) 。这是未定义行为,可能导致崩溃或数据损坏。

Swift 并发模型不再询问“代码在哪里运行”,而是问:“谁有权访问这块数据?

这就是 隔离(Isolation)

Swift 通过编译器在构建阶段强制执行隔离规则,而不是依赖运行时的运气。底层依然是线程池在调度,但上层的安全由 Actor 模型保证。

1. MainActor:UI 的守护者

@MainActor 是一个全局 Actor,代表主线程的隔离域。它是 UI 框架(SwiftUI, UIKit)的领地。

@MainActor
class ViewModel {
    // 编译器强制要求:访问 items 必须在 MainActor 上
    var items: [Item] = [] 
}

标记了 @MainActor 的类,其属性和方法默认都在主线程隔离域中。这意味着你不需要手动 DispatchQueue.main.async,编译器会确保外部调用者必须通过 await 来跨越隔离边界。对于大多数应用,将 ViewModel 标记为 @MainActor 是默认且正确的选择。

2. Actor:数据孤岛

actor 是一种引用类型,它像类一样,但有一个关键区别:它保护其可变状态。Actor 保证同一时间只有一个任务能访问其内部状态,从而从根本上消除了数据竞争。

actor BankAccount {
    var balance: Double = 0
    
    func deposit(_ amountDouble) {
        balance += amount // 安全:Actor 内部串行访问
    }
}

// 外部调用必须等待,因为可能需要排队
await account.deposit(100)

可以将 Actor 想象成办公楼里的独立办公室,一次只能进一个人处理文件。

3. Nonisolated:公共走廊

标记为 nonisolated 的代码显式退出了 Actor 的隔离保护。它可以被任何地方调用,不需要 await,但也因此不能访问 Actor 的内部受保护状态。

数据的跨域传递:Sendable

隔离域保护了数据,但数据总需要在不同域之间传递。当一个对象从后台 Actor 传递到 MainActor 时,Swift 必须确保这一传递是安全的。

Sendable 协议就是这个通行证。它告诉编译器:“这个类型可以安全地跨越隔离边界”。

  • • 值类型(Struct, Enum) :通常是 Sendable,因为传递的是拷贝,互不影响。
  • • Actor:也是 Sendable,因为它们自带同步机制。
  • • 类(Class) :通常 不是 Sendable。除非它是 final 的且只有不可变属性。

如果试图在并发环境中传递一个普通的类实例,编译器会报错,因为它无法保证两个线程不会同时修改这个类。

隔离的继承与流转

理解 Swift 并发的关键在于理解 隔离继承

在启用了完整并发检查(Swift 6 / Approachable Concurrency)的项目中,代码执行的上下文通常遵循以下规则:

  1. 1. 函数调用:继承调用者的隔离。如果在 @MainActor 的函数中调用另一个普通函数,后者也在 MainActor 上运行。
  2. 2. Task { } :继承创建它的上下文。在 ViewModel(MainActor)中创建的 Task,其中的代码默认也在 MainActor 上运行。
  3. 3. Task.detached:斩断继承,在一个没有任何特定隔离的上下文中运行。

这也是为什么不要迷信 async 等于后台线程。

@MainActor
func slowFunction() async {
    // 错误:这虽然是 async 函数,但依然在 MainActor 运行
    // 这里的同步计算会卡死 UI
    let result = expensiveCalculation() 
    data = result
}

async 只意味着函数 可以 暂停,并不意味着它会自动切到后台。如果是 CPU 密集型任务,你需要显式地将其移出主线程(例如使用 Swift 6.2 的 @concurrent 标记或放入 detached task)。

常见误区与避坑指南

  1. 1. 过度设计 Actor:不要为每个数据源都创建一个 Actor。大多数时候,将状态隔离在 @MainActor 的 ViewModel 中已经足够。只有当确实存在跨线程共享的可变状态时,才引入自定义 Actor。
  2. 2. 滥用 @unchecked Sendable:不要为了消除编译器警告而随意使用 @unchecked Sendable。这相当于告诉编译器“闭嘴,由于我自己负责”,一旦出错就是难以调试的竞争问题。
  3. 3. 阻塞协作线程池:永远不要在 async 上下文中使用信号量(Semaphore)或 DispatchGroup.wait()。Swift 的底层线程池容量有限(通常等同于 CPU 核心数),阻塞其中一个线程可能导致死锁或饥饿。
  4. 4. 无脑 MainActor.run:很多开发者习惯在获取数据后写 await MainActor.run { ... }。更好的做法是直接将更新数据的函数标记为 @MainActor,让编译器自动处理上下文切换。

总结

Swift 的并发模型建立在三个支柱之上:

  1. 1. async/await:处理控制流,让异步代码线性化。
  2. 2. Task:结构化地管理异步工作的生命周期。
  3. 3. Actor & Isolation:通过隔离域在编译时消除数据竞争。

对于大多数应用开发,遵循简单的规则即可:默认使用 @MainActor 保护 UI 状态,使用 async/await 处理 I/O,利用 .task 管理生命周期。只有在遇到真正的性能瓶颈或复杂的共享状态时,才需要深入自定义 Actor 和细粒度的隔离控制。

编译器是你的向导,而非敌人。当它报出并发错误时,它实际上是在帮你规避那些曾在旧时代导致无数崩溃的隐形 Bug。

1月10日用户隐私保护新规出炉,政策解读

2026年1月10日,国家互联网信息办公室发布了《互联网应用程序个人信息收集使用规定(征求意见稿)》,进一步优化了个人隐私保护法案内容。

政策原文:mp.weixin.qq.com/s/epF6mh-Oc…

原文.png

一句话总结:这次的新政细化了隐私合规规则,堵住了一些规则漏洞,进一步保护用户隐私。对于大部分开展正规业务的开发者来说,无需特别的改动。后续可按渠道平台(华为、小米等)要求,做进一步调整

内容概览
1、明确禁止“无关场景调用相机/麦克风”,直击“偷听偷拍”乱象。——旧规:仅原则性要求“不得超范围收集”,但未明确哪些行为算违规。
2、位置权限分级管理:区分“实时定位”与“单次定位” ——旧规:仅笼统要求“最小必要”。
3、进一步强化了不允许获取用户全部相册权限,必须使用系统系框架Android SAF,只能获取用户授权后的部分照片。
4、操作系统厂商,需提供“精细化授权”选项,如 “仅本次允许”“仅今天允许”。
5、生物识别信息(人脸、指纹等)原则上只能本地存储,不能上传。除非法律允许或用户单独同意。
6、App运营者对第三方SDK负连带审核义务。用户向App提出对SDK的数据权利请求(如删除),App必须转达并督促SDK响应,不能再以“这是第三方SDK行为,与我无关”推责。
7、账号注销流程进一步简化:不得强制用户提供额外身份证明(如手持身份证、学历证明等)。堵住了一些App以“安全验证”为名设置注销门槛的做法。

下面是详细介绍

一、首次 明确禁止“无关场景调用相机/麦克风” —— 直击“偷听偷拍”乱象

  • 旧规:仅原则性要求“不得超范围收集”,但未明确哪些行为算违规。
  • 新规(第14条)
    • 必须“用户主动选择使用拍照、语音、录音录像等功能时”才能调用相机/麦克风
    • 禁止在用户停止使用相关功能后继续调用
    • 禁止在无关场景(如浏览商品页、看新闻)调用音视频权限

实质变化:这是首次以部门规章形式将“后台静默调用麦克风/摄像头”直接定性为违规。此前企业常以“预加载”“性能优化”为由辩解,今后不再成立。


二、位置权限分级管理:区分“实时定位”与“单次定位”

  • 旧规:仅笼统要求“最小必要”。
  • 新规(第14条)
    • 实时定位类(导航、外卖) → 调用频率必须“限于业务最低频度”;
    • 单次定位类(搜索、推荐、广告)仅允许调用一次,且需用户进入界面或主动刷新;
    • 原则上禁止申请“后台持续获取位置”权限(除非法律另有规定或确需)。

实质变化:终结了“只要用户开了定位,App就可高频后台上报位置”的灰色操作。例如,电商App在首页展示附近门店,只能触发一次定位,不能持续追踪。


三、强制使用系统级存储访问框架(如Android SAF)

  • 新规(第14条)
    • 用户上传图片/文件时,若系统提供标准存储访问框架(如Android的Storage Access Framework),App 不得再索要“相册”“存储”全权限
    • 即使因文件编辑/备份获得存储权限,也不得访问用户未主动选择的其他文件

实质变化:推动从“粗放式读取整个相册”转向“按需访问单个文件”,大幅降低隐私泄露面。这要求开发者重构文件上传逻辑。


四、操作系统需提供“精细化授权”选项(开发者需适配)

  • 新规(第14条)
    • 操作系统在弹窗征得用户同意时,应提供基于时间、频度、精度的授权选项(如“仅本次允许”“仅今天允许”“模糊位置”)。

实质变化:虽然责任在OS厂商,但开发者需确保App能兼容这些细粒度授权(例如用户选择“仅本次允许位置”,下次使用需重新申请)。否则功能将异常。


五、生物识别信息默认本地处理,禁止网络传输

  • 新规(第15条)
    • 人脸、指纹等生物特征信息,默认应在终端设备本地处理和存储
    • 不得通过网络传输至服务器,除非:
      • 法律法规明确允许;或
      • 用户单独书面同意(且目的充分必要)。

实质变化:许多App当前将人脸照片上传服务器进行比对(如刷脸登录),今后必须评估是否真有必要。若非必要,必须改为本地验证(如Face ID/指纹API)。


六、SDK责任穿透:App运营者对第三方SDK负连带审核义务

  • 新规(第19条)
    • App运营者必须审核嵌入的SDK,确保其行为符合公示规则;
    • 用户向App提出对SDK的数据权利请求(如删除),App必须转达并督促SDK响应

实质变化:不能再以“这是第三方SDK行为,与我无关”推责。开发者需建立SDK准入机制,并保留沟通记录。


七、账号注销流程进一步简化(禁止设置障碍)

  • 新规(第18条)
    • 注销后15个工作日内必须删除或匿名化数据
    • 不得强制用户提供额外身份证明(如手持身份证、学历证明等);
    • 若使用统一账号体系(如微信/QQ登录),必须支持单App注销,不影响其他服务。

实质变化:堵住了一些App以“安全验证”为名设置注销门槛的做法。

Claude Code 四大核心技能使用指南

本文详细介绍 Superpowers、Feature-Dev、UI/UX Pro Max 和 Ralph Wiggum 四个强大技能的使用方法,帮助开发者充分发挥 Claude Code 的潜力。


目录

  1. 技能系统概述
  2. Superpowers:完整开发工作流
  3. Feature-Dev:功能开发指南
  4. UI/UX Pro Max:设计智能系统
  5. Ralph Wiggum:迭代循环开发
  6. 技能选择指南
  7. 总结

技能系统概述

Claude Code 的技能系统是一套可组合的专业工作流,它们在特定场景下自动激活,帮助开发者以系统化的方式完成复杂任务。

核心原则

如果你认为某个技能有哪怕 1% 的可能适用于当前任务,
你就必须调用它。这不是建议,而是强制要求。

技能优先级

当多个技能可能适用时,按以下顺序使用:

  1. 流程技能优先(brainstorming、debugging)- 决定如何处理任务
  2. 实现技能其次(frontend-design、mcp-builder)- 指导具体执行

Superpowers:完整开发工作流

什么是 Superpowers?

Superpowers 是一套完整的软件开发工作流,基于可组合的"技能"构建。它从你启动编程代理的那一刻开始工作,不是直接跳入编码,而是先退一步理解你真正想要做什么。

安装方式

Claude Code 用户:

# 注册 marketplace
/plugin marketplace add obra/superpowers-marketplace

# 安装插件
/plugin install superpowers@superpowers-marketplace

# 验证安装
/help

核心工作流

Superpowers 包含七个阶段的完整开发流程:

1. Brainstorming(头脑风暴)

在编写代码之前激活,通过问答细化粗略想法,探索替代方案,分段展示设计供验证。

关键原则:

  • 一次只问一个问题
  • 优先使用选择题
  • 无情地应用 YAGNI(你不会需要它)
  • 总是提出 2-3 种方案后再定案

流程:

理解项目状态 → 逐个提问细化想法 → 提出2-3种方案
→ 分段展示设计(每段200-300字)→ 验证后保存设计文档

2. Git Worktrees(Git工作树)

设计批准后激活,在新分支上创建隔离的工作空间,运行项目设置,验证干净的测试基线。

3. Writing Plans(编写计划)

将工作分解为小任务(每个2-5分钟),每个任务都有:

  • 精确的文件路径
  • 完整的代码
  • 验证步骤

4. Subagent-Driven Development(子代理驱动开发)

这是 Superpowers 的核心机制:

每个任务分派新的子代理 → 两阶段审查:
  1. 规格合规审查(代码是否符合规格)
  2. 代码质量审查(代码是否写得好)

优势:

  • 每个任务有新鲜的上下文(无污染)
  • 自动审查检查点
  • 子代理可以在工作前后提问

示例流程:

读取计划 → 提取所有任务 → 创建TodoWrite

任务1[分派实现子代理] → 子代理实现、测试、提交
  [分派规格审查子代理] → 确认代码符合规格
  [分派代码质量审查子代理] → 批准代码质量
  [标记任务完成]

任务2: ...

所有任务完成后 → 最终代码审查 → 完成开发分支

5. Test-Driven Development(测试驱动开发)

Superpowers 强制执行 RED-GREEN-REFACTOR 循环:

写失败测试 → 观察失败 → 写最小代码 → 观察通过 → 提交

铁律:

没有先失败的测试,就没有生产代码

在测试之前写了代码?删除它。从头开始。

常见借口及真相:

借口 真相
"太简单不需要测试" 简单代码也会出错,测试只需30秒
"我之后会测试" 立即通过的测试什么也证明不了
"删除X小时的工作太浪费" 沉没成本谬误,保留未验证的代码才是技术债务
"TDD太教条" TDD才是务实的,"务实"的捷径=生产环境调试=更慢

6. Code Review(代码审查)

在任务之间激活,根据计划审查代码,按严重程度报告问题。关键问题会阻止进度。

7. Finishing Branch(完成分支)

任务完成时激活,验证测试,提供选项(合并/PR/保留/丢弃),清理工作树。

核心哲学

  • 测试驱动开发 - 始终先写测试
  • 系统化优于临时 - 流程优于猜测
  • 降低复杂性 - 简单是首要目标
  • 证据优于声明 - 在宣布成功前验证

Feature-Dev:功能开发指南

什么是 Feature-Dev?

Feature-Dev 是一个系统化的功能开发技能,帮助开发者深入理解代码库、识别并询问所有不明确的细节、设计优雅的架构,然后实现。

七个阶段

Phase 1: Discovery(发现)

目标: 理解需要构建什么

操作:

  1. 创建包含所有阶段的 todo 列表

  2. 如果功能不清晰,询问用户:

    • 要解决什么问题?
    • 功能应该做什么?
    • 有什么约束或要求?
  3. 总结理解并与用户确认

Phase 2: Codebase Exploration(代码库探索)

目标: 在高层和底层理解相关现有代码和模式

操作:

  1. 并行启动 2-3 个 code-explorer 代理,每个代理:

    • 全面追踪代码,专注于理解抽象、架构和控制流
    • 针对代码库的不同方面
    • 包含 5-10 个关键文件列表

示例代理提示:

  • "找到与 [功能] 类似的功能并全面追踪其实现"
  • "映射 [功能区域] 的架构和抽象"
  • "分析 [现有功能/区域] 的当前实现"
  1. 代理返回后,阅读所有识别的文件以建立深入理解
  2. 呈现发现和模式的综合摘要

Phase 3: Clarifying Questions(澄清问题)

目标: 在设计前填补空白并解决所有歧义

这是最重要的阶段之一,不能跳过。

操作:

  1. 审查代码库发现和原始功能请求
  2. 识别未明确的方面:边缘情况、错误处理、集成点、范围边界、设计偏好、向后兼容性、性能需求
  3. 以清晰、有组织的列表向用户呈现所有问题
  4. 等待答案后再进行架构设计

Phase 4: Architecture Design(架构设计)

目标: 设计具有不同权衡的多种实现方案

操作:

  1. 并行启动 2-3 个 code-architect 代理,关注不同方面:

    • 最小变更:最小变化,最大复用
    • 清洁架构:可维护性,优雅抽象
    • 务实平衡:速度 + 质量
  2. 审查所有方案,形成哪个最适合此特定任务的意见

  3. 向用户呈现:

    • 每种方案的简要摘要
    • 权衡比较
    • 你的推荐及理由
    • 具体实现差异
  4. 询问用户偏好哪种方案

Phase 5: Implementation(实现)

目标: 构建功能

未经用户批准不要开始

操作:

  1. 等待用户明确批准
  2. 阅读前几个阶段识别的所有相关文件
  3. 按选定架构实现
  4. 严格遵循代码库约定
  5. 编写干净、文档完善的代码
  6. 随着进展更新 todos

Phase 6: Quality Review(质量审查)

目标: 确保代码简单、DRY、优雅、易读且功能正确

操作:

  1. 并行启动 3 个 code-reviewer 代理,关注不同方面:

    • 简单性/DRY/优雅
    • 缺陷/功能正确性
    • 项目约定/抽象
  2. 整合发现,识别你建议修复的最高严重性问题

  3. 向用户呈现发现并询问他们想怎么做(现在修复、稍后修复或按原样进行)

  4. 根据用户决定处理问题

Phase 7: Summary(总结)

目标: 记录完成的工作

操作:

  1. 将所有 todos 标记为完成

  2. 总结:

    • 构建了什么
    • 做出的关键决策
    • 修改的文件
    • 建议的下一步

UI/UX Pro Max:设计智能系统

什么是 UI/UX Pro Max?

UI/UX Pro Max 是一个可搜索的 UI 设计数据库,包含 50+ 种 UI 风格、21 种调色板、50 种字体配对、20 种图表类型、8 种技术栈的最佳实践。

前提条件

确保已安装 Python:

python3 --version || python --version

使用方法

当用户请求 UI/UX 工作(设计、构建、创建、实现、审查、修复、改进)时,按以下工作流程:

步骤 1:分析用户需求

从用户请求中提取关键信息:

  • 产品类型:SaaS、电商、作品集、仪表盘、着陆页等
  • 风格关键词:极简、活泼、专业、优雅、深色模式等
  • 行业:医疗、金融科技、游戏、教育等
  • 技术栈:React、Vue、Next.js,或默认使用 html-tailwind

步骤 2:搜索相关领域

使用 search.py 多次搜索以收集全面信息:

python3 .claude/skills/ui-ux-pro-max/scripts/search.py "<关键词>" --domain <领域> [-n <最大结果数>]

推荐搜索顺序:

顺序 领域 用途
1 product 获取产品类型的风格推荐
2 style 获取详细风格指南(颜色、效果、框架)
3 typography 获取字体配对和 Google Fonts 导入
4 color 获取配色方案(主色、辅色、CTA、背景、文字、边框)
5 landing 获取页面结构(如果是着陆页)
6 chart 获取图表推荐(如果是仪表盘/分析)
7 ux 获取最佳实践和反模式
8 stack 获取技术栈特定指南

步骤 3:可用技术栈

关注点
html-tailwind Tailwind 工具类、响应式、无障碍(默认)
react 状态、hooks、性能、模式
nextjs SSR、路由、图片、API 路由
vue Composition API、Pinia、Vue Router
svelte Runes、stores、SvelteKit
swiftui 视图、状态、导航、动画
react-native 组件、导航、列表
flutter Widgets、状态、布局、主题

示例工作流

用户请求: "做一个专业护肤服务的着陆页"

# 1. 搜索产品类型
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --domain product

# 2. 搜索风格
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "elegant minimal soft" --domain style

# 3. 搜索字体
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "elegant luxury" --domain typography

# 4. 搜索配色
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness" --domain color

# 5. 搜索着陆页结构
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "hero-centric social-proof" --domain landing

# 6. 搜索 UX 指南
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "animation" --domain ux
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux

# 7. 搜索技术栈指南
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "layout responsive" --stack html-tailwind

专业 UI 通用规则

这些是经常被忽视但会让 UI 看起来不专业的问题:

图标和视觉元素

规则 正确做法 错误做法
不使用 emoji 图标 使用 SVG 图标(Heroicons、Lucide) 使用 emoji 作为 UI 图标
稳定的悬停状态 使用颜色/透明度过渡 使用会移动布局的缩放变换
一致的图标尺寸 使用固定 viewBox(24x24)配合 w-6 h-6 随意混合不同图标尺寸

交互和光标

规则 正确做法 错误做法
光标指针 给所有可点击元素添加 cursor-pointer 交互元素保持默认光标
悬停反馈 提供视觉反馈(颜色、阴影、边框) 元素交互时无任何指示
平滑过渡 使用 transition-colors duration-200 瞬间状态变化或太慢(>500ms)

亮/暗模式对比度

规则 正确做法 错误做法
亮模式玻璃卡片 使用 bg-white/80 或更高透明度 使用 bg-white/10(太透明)
亮模式文字对比 使用 #0F172A(slate-900)作为文字 使用 #94A3B8(slate-400)作为正文
边框可见性 亮模式使用 border-gray-200 使用 border-white/10(不可见)

交付前检查清单

视觉质量

  • 没有使用 emoji 作为图标
  • 所有图标来自一致的图标集
  • 品牌 logo 正确
  • 悬停状态不会导致布局偏移

交互

  • 所有可点击元素有 cursor-pointer
  • 悬停状态提供清晰的视觉反馈
  • 过渡平滑(150-300ms)
  • 键盘导航的焦点状态可见

亮/暗模式

  • 亮模式文字有足够对比度(最少 4.5:1)
  • 玻璃/透明元素在亮模式下可见
  • 边框在两种模式下都可见

布局

  • 浮动元素与边缘有适当间距
  • 内容不会隐藏在固定导航栏后面
  • 响应式适配 320px、768px、1024px、1440px
  • 移动端无水平滚动

Ralph Wiggum:迭代循环开发

什么是 Ralph Wiggum?

Ralph Wiggum 是一种基于持续 AI 代理循环的开发方法。正如 Geoffrey Huntley 所描述的: "Ralph 是一个 Bash 循环" - 一个简单的 while true,重复给 AI 代理喂入提示文件,让它迭代改进工作直到完成。

这个技术以《辛普森一家》中的 Ralph Wiggum 命名,体现了不顾挫折持续迭代的哲学。

核心概念

这个插件使用 Stop hook 实现 Ralph,拦截 Claude 的退出尝试:

# 你只运行一次:
/ralph-loop "你的任务描述" --completion-promise "DONE"

# 然后 Claude Code 自动:
# 1. 处理任务
# 2. 尝试退出
# 3. Stop hook 阻止退出
# 4. Stop hook 喂入相同的提示
# 5. 重复直到完成

循环发生在你当前会话内 - 你不需要外部 bash 循环。

这创建了一个自引用反馈循环

  • 迭代之间提示不变
  • Claude 之前的工作保留在文件中
  • 每次迭代看到修改的文件和 git 历史
  • Claude 通过读取文件中自己过去的工作自主改进

快速开始

/ralph-loop "构建一个 todos 的 REST API。要求:CRUD 操作、输入验证、测试。完成后输出 <promise>COMPLETE</promise>。" --max-iterations 50 --completion-promise "COMPLETE"

Claude 将:

  • 迭代实现 API
  • 运行测试并看到失败
  • 根据测试输出修复 bug
  • 迭代直到满足所有要求
  • 完成后输出完成承诺

命令

/ralph-loop

在当前会话中启动 Ralph 循环。

/ralph-loop "<提示>" --max-iterations <n> --completion-promise "<文本>"

选项:

  • --max-iterations <n> - N 次迭代后停止(默认:无限)
  • --completion-promise <text> - 表示完成的短语

/cancel-ralph

取消活动的 Ralph 循环。

/cancel-ralph

提示编写最佳实践

1. 清晰的完成标准

错误示例:

构建一个 todo API 并让它好用。

正确示例:

构建一个 todos 的 REST API。

完成条件:
- 所有 CRUD 端点工作正常
- 输入验证就位
- 测试通过(覆盖率 > 80%)
- 带 API 文档的 README
- 输出:<promise>COMPLETE</promise>

2. 增量目标

错误示例:

创建一个完整的电商平台。

正确示例:

阶段 1:用户认证(JWT、测试)
阶段 2:产品目录(列表/搜索、测试)
阶段 3:购物车(添加/删除、测试)

所有阶段完成后输出 <promise>COMPLETE</promise>。

3. 自我纠正

错误示例:

为功能 X 写代码。

正确示例:

使用 TDD 实现功能 X:
1. 写失败测试
2. 实现功能
3. 运行测试
4. 如果失败,调试并修复
5. 需要时重构
6. 重复直到全部通过
7. 输出:<promise>COMPLETE</promise>

4. 安全阀

始终使用 --max-iterations 作为安全网,防止在不可能的任务上无限循环:

# 推荐:始终设置合理的迭代限制
/ralph-loop "尝试实现功能 X" --max-iterations 20

哲学

Ralph 体现几个关键原则:

原则 说明
迭代 > 完美 不要追求第一次就完美。让循环细化工作。
失败是数据 "确定性的失败"意味着失败是可预测的和有信息量的。
操作员技能很重要 成功取决于写好提示,不只是有好模型。
坚持获胜 持续尝试直到成功。循环自动处理重试逻辑。

适用场景

适合:

  • 有明确成功标准的定义良好的任务
  • 需要迭代和细化的任务(如让测试通过)
  • 你可以走开的绿地项目
  • 有自动验证的任务(测试、linter)

不适合:

  • 需要人类判断或设计决策的任务
  • 一次性操作
  • 成功标准不清楚的任务
  • 生产环境调试(使用针对性调试代替)

真实世界成果

  • 在 Y Combinator 黑客马拉松测试中一夜成功生成 6 个仓库
  • 一份 50k合同以50k 合同以 297 API 成本完成
  • 用这种方法在 3 个月内创建了整个编程语言("cursed")

技能选择指南

场景对照表

场景 推荐技能
构建新功能 Feature-Dev → Superpowers
UI/UX 设计实现 UI/UX Pro Max
长时间自主任务 Ralph Wiggum
完整项目开发 Superpowers(完整工作流)
修复 bug Superpowers(systematic-debugging)
代码审查 Superpowers(code-reviewer)

组合使用

这些技能可以组合使用:

  1. Feature-Dev + UI/UX Pro Max:开发带 UI 的新功能
  2. Ralph Wiggum + Superpowers:自主完成带 TDD 的长任务
  3. Superpowers + Feature-Dev:完整的企业级功能开发

总结

技能 核心价值 最佳场景
Superpowers 完整的 TDD 工作流 项目开发全流程
Feature-Dev 系统化功能开发 新功能实现
UI/UX Pro Max 设计智能数据库 UI 设计和前端开发
Ralph Wiggum 自主迭代循环 长时间自动化任务

黄金法则

如果你认为某个技能有哪怕 1% 的可能适用,就必须使用它。
这不是可选的,这是强制的。你不能为绕过它找理由。

iOS实现 WKWebView 长截图的优雅方案

在 iOS 开发中,为 WKWebView 实现长截图功能是一个常见且棘手的需求。开发者通常会遇到以下几个痛点:

  • 网页内容高度不确定
  • 滚动区域难以完整截取
  • 截图过程中的界面闪烁影响用户体验

本文将介绍一种高效、稳定的解决方案,通过分段渲染图像拼接,完美捕获整个网页内容,并提供可直接集成的完整代码。


🎯 核心思路

我们的方案主要分为三个清晰的步骤:

  1. 布局调整:将 WebView 移至临时容器,为完整渲染做准备。
  2. 分段渲染:按屏幕高度分段捕获内容,生成多张切片图像。
  3. 图像拼接:将所有切片图像无缝拼接成一张完整的长图。

这种方法巧妙地绕过了直接截取 UIScrollView 的局限性,同时通过遮罩视图,保证了用户界面的视觉稳定性,避免闪烁。


💻 完整实现代码

WKWebView分类中添加长截图方法

  • WKWebView+Capture.h
#import <WebKit/WebKit.h>
#import <UIKit/UIKit.h>

NS_ASSUME_NONNULL_BEGIN

@interface WKWebView (Capture)

/**
 * 捕获 WKWebView 的完整内容并生成长截图
 * @param completion 完成回调,返回拼接好的长图(失败则返回 nil)
 */
- (void)captureEntireWebViewWithCompletion:(void (^)(UIImage * _Nullable capturedImage))completion;

@end

NS_ASSUME_NONNULL_END


  • WKWebView+Capture.m
#import "WKWebView+Capture.h"

@implementation WKWebView (Capture)

/**
 * 捕获 WKWebView 的完整内容并生成长截图
 * @param completion 完成回调,返回拼接好的长图(失败则返回 nil)
 */
- (void)captureEntireWebViewWithCompletion:(void (^)(UIImage *capturedImage))completion {

    // ⚠️ 关键:确保在主线程执行
    if (![NSThread isMainThread]) {
        NSLog(@"错误:WebView 截图必须在主线程执行");
        if (completion) completion(nil);
        return;
    }

    // 步骤1: 检查父视图并保存原始状态
    UIView *parentView = self.superview;
    if (!parentView) {
        if (completion) completion(nil);
        return;
    }

    CGRect originalFrame = self.frame;
    CGPoint originalContentOffset = self.scrollView.contentOffset;

    // 步骤2: 创建遮罩视图,保持界面"静止"的视觉效果,可以额外添加loading
    UIView *snapshotCoverView = [self snapshotViewAfterScreenUpdates:NO];
    snapshotCoverView.frame = self.frame; // 确保遮罩视图位置与 WebView 完全一致
    [parentView insertSubview:snapshotCoverView aboveSubview:self];

    // 步骤3: 创建隐藏的临时窗口和容器
    UIWindow *temporaryWindow = [[UIWindow alloc] initWithFrame:self.bounds];
    temporaryWindow.windowLevel = UIWindowLevelNormal - 1000; // 置于底层
    temporaryWindow.hidden = NO;
    temporaryWindow.alpha = 0;
    temporaryWindow.userInteractionEnabled = NO;

    UIView *captureContainerView = [[UIView alloc] initWithFrame:self.bounds];
    captureContainerView.clipsToBounds = YES;

    // 将 WebView 移入临时容器
    [self removeFromSuperview];
    [captureContainerView addSubview:self];
    [temporaryWindow addSubview:captureContainerView];

    // 步骤4: 获取完整内容高度并调整布局
    CGFloat fullContentHeight = self.scrollView.contentSize.height;
    self.frame = CGRectMake(0, 0, originalFrame.size.width, fullContentHeight);
    self.scrollView.contentOffset = CGPointZero;

    __weak typeof(self) weakSelf = self;

    // ⭐ 延迟执行,确保 WebView 内容布局与渲染完成
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(0.5 * NSEC_PER_SEC)),
                   dispatch_get_main_queue(), ^{
        __strong typeof(weakSelf) strongSelf = weakSelf;
        if (!strongSelf) {
            if (completion) completion(nil);
            return;
        }

        // 步骤5: 分段截图核心逻辑
        CGFloat pageHeight = captureContainerView.bounds.size.height; // 单屏高度
        CGFloat totalHeight = fullContentHeight; // 总内容高度

        NSMutableArray<UIImage *> *imageSlices = [NSMutableArray array];
        CGFloat offsetY = 0;

        while (offsetY < totalHeight) {
            CGFloat remainingHeight = totalHeight - offsetY;
            CGFloat sliceHeight = MIN(pageHeight, remainingHeight);

            // 处理最后一段高度不足一屏的情况
            if (remainingHeight < pageHeight) {
                CGRect containerFrame = captureContainerView.frame;
                containerFrame.size.height = remainingHeight;
                captureContainerView.frame = containerFrame;
            }

            // 移动 WebView,将当前要截取的区域"暴露"出来
            CGRect webViewFrame = strongSelf.frame;
            webViewFrame.origin.y = -offsetY;
            strongSelf.frame = webViewFrame;

            // 渲染当前分段到图像上下文
            UIGraphicsBeginImageContextWithOptions(
                CGSizeMake(originalFrame.size.width, sliceHeight),
                NO,
                [UIScreen mainScreen].scale
            );

            CGContextRef context = UIGraphicsGetCurrentContext();
            CGFloat scaleX = originalFrame.size.width / captureContainerView.bounds.size.width;
            CGFloat scaleY = sliceHeight / captureContainerView.bounds.size.height;
            CGContextScaleCTM(context, scaleX, scaleY);

            [captureContainerView.layer renderInContext:context];
            UIImage *sliceImage = UIGraphicsGetImageFromCurrentImageContext();
            UIGraphicsEndImageContext();

            if (sliceImage) {
                [imageSlices addObject:sliceImage];
            }

            offsetY += sliceHeight; // 移动到下一段
        }

        UIImage *finalImage = nil;

        // 步骤6: 图像拼接
        if (imageSlices.count == 1) {
            finalImage = imageSlices.firstObject;
        } else if (imageSlices.count > 1) {
            UIGraphicsBeginImageContextWithOptions(
                CGSizeMake(originalFrame.size.width, totalHeight),
                NO,
                [UIScreen mainScreen].scale
            );

            CGFloat drawOffsetY = 0;
            for (UIImage *slice in imageSlices) {
                [slice drawInRect:CGRectMake(0,
                                             drawOffsetY,
                                             slice.size.width,
                                             slice.size.height)];
                drawOffsetY += slice.size.height;
            }

            finalImage = UIGraphicsGetImageFromCurrentImageContext();
            UIGraphicsEndImageContext();
        }

        // 步骤7: 恢复原始状态
        [strongSelf removeFromSuperview];
        [captureContainerView removeFromSuperview];
        temporaryWindow.hidden = YES;

        strongSelf.frame = originalFrame;
        strongSelf.scrollView.contentOffset = originalContentOffset;
        [parentView insertSubview:strongSelf belowSubview:snapshotCoverView];
        [snapshotCoverView removeFromSuperview];

        // 步骤8: 在主线程回调最终结果
        if (completion) {
            completion(finalImage);
        }
    });
}

@end


📱 效果展示

长截图展示

🚀 使用方法

调用方式非常简单,只需一行代码。

// 在需要截图的地方调用
[webView captureEntireWebViewWithCompletion:^(UIImage *capturedImage) {
    if (capturedImage) {
        // ✅ 截图成功,处理结果
        // 例如:保存到相册
        UIImageWriteToSavedPhotosAlbum(capturedImage, nil, nil, nil);
        // 或:上传、分享、预览等
    } else {
        // ❌ 截图失败
        NSLog(@"截图失败");
    }
}];

📝 总结

本文提供的方案通过以下关键技术,优雅地解决了 WKWebView 长截图的难题:

  • 临时容器管理:隔离渲染环境,避免干扰主界面。
  • 分段渲染:将长内容分解为多个可管理的屏幕片段。
  • 状态恢复:完整保存并恢复 WebView 的原始状态,确保业务无感知。

如果你有更好的实现思路,或在实际应用中遇到了特殊场景,欢迎在评论区分享交流!

Swift 方法派发深度探究

引言:一个危险的实验

想象一下,你正在调试一个复杂的 iOS 应用,想要在不修改源码的情况下监控所有 UIViewControllerviewDidAppear 调用;还有如果要支持热修复,该如何?你可能会想到使用 Method Swizzling

extension UIViewController {
    @objc dynamic func swizzled_viewDidAppear(_ animated: Bool) {
        print("🎯 [AOP] \(type(of: self)) 显示")
        swizzled_viewDidAppear(animated) // 调用原始实现
    }
    
    static func swizzleViewDidAppear() {
        let original = #selector(viewDidAppear(_:))
        let swizzled = #selector(swizzled_viewDidAppear(_:))
        
        guard let originalMethod = class_getInstanceMethod(self, original),
              let swizzledMethod = class_getInstanceMethod(self, swizzled) else {
            return
        }
        
        method_exchangeImplementations(originalMethod, swizzledMethod)
    }
}

看起来完美,对吧?但这里隐藏着一个 Swift 的重要秘密:为什么必须使用 @objc dynamic 如果去掉 dynamic 会发生什么?

Part 1: 为什么 Swizzling 需要动态派发?

1.1 Swizzling 的工作原理

Method Swizzling 本质上是在运行时交换两个方法的实现。它依赖 Objective-C 运行时的消息派发机制:

// Objective-C 运行时的工作方式
objc_msgSend(object, selector, ...)

当调用 [object method] 时,运行时:

  1. 根据对象的类查找方法列表
  2. 找到对应 selector 的实现(IMP)
  3. 执行该实现

Swizzling 就是修改了第 2 步的映射关系。

1.2 Swift 与 Objective-C 的冲突

问题在于:Swift 默认不使用消息派发

class MyClass {
    func normalMethod() { }     // Swift 默认派发
    @objc func exposedMethod() { }  // 对 OC 可见,但仍不是消息派发
    @objc dynamic func dynamicMethod() { }  // 这才是消息派发
}

如果你尝试 Swizzle 一个非 dynamic 的方法:

class TestSwizzle: NSObject {
    @objc func original() { print("Original") }
    @objc func swizzled() { print("Swizzled") }
    
    static func attemptSwizzle() {
        let original = #selector(original)
        let swizzled = #selector(swizzled)
        
        guard let origMethod = class_getInstanceMethod(self, original),
              let swizMethod = class_getInstanceMethod(self, swizzled) else {
            return
        }
        
        print("交换前:")
        print("original IMP: \(method_getImplementation(origMethod))")
        print("swizzled IMP: \(method_getImplementation(swizMethod))")
        
        method_exchangeImplementations(origMethod, swizMethod)
        
        print("交换后:")
        print("original IMP: \(method_getImplementation(origMethod))")
        print("swizzled IMP: \(method_getImplementation(swizMethod))")
        
        let test = TestSwizzle()
        test.original()  // 输出什么?
    }
}

运行结果可能让你困惑:

交换前:
original IMP: 0x0000000102f7fbc0
swizzled IMP: 0x0000000102f7fcc0

交换后:
original IMP: 0x0000000102f7fcc0
swizzled IMP: 0x0000000102f7fbc0

Original   //❓ 调用结果还是 "Original"

为什么 IMP 发生交换后,但行为没变?

Part 2: Swift 的三种派发方式

2.1 派发方式对比

假设大家已有概念,为了方便快速浏览,我把这些汇总到了一个表格:

特性 直接派发 (Direct Dispatch) 表派发 (Table Dispatch) 消息派发 (Message Dispatch)
Swift 写法 final func
struct 的方法
extension 中的方法
private/fileprivate func
class func (默认)
@objc func (仅 Swift 内)
@objc dynamic func
@objc dynamic var
调用方式 编译时确定地址,直接跳转 通过在类对象虚函数表查找 Objective-C 运行时 objc_msgSend
性能 ⚡️ 最快 (几乎无开销) 较快 (一次指针查找) 🐌 最慢 (哈希查找+缓存)
灵活性 ❌ 最低 (无法重写) ✅ 中等 (支持继承重写) ✅✅ 最高 (支持运行时修改)
内存占用 无额外开销 每个类一个虚函数表 每个类方法列表 + 缓存
重写支持 ❌ 不支持 ✅ 支持 ✅ 支持
运行时修改 ❌ 不可能 ❌ 不可能 (Swift 5+) ✅ 可能 (Method Swizzling)
KVO 支持 ❌ 不支持 ❌ 不支持 ✅ 支持
典型应用 工具方法、性能关键代码 普通业务逻辑、可继承的类 需要动态特性的代码
二进制影响 最小 中等 最大 (生成 OC 元数据)
调试难度 简单 中等 困难 (调用栈复杂)

2.2 方法派发特别注意点

extension 中的方法特别说明:

extension 中的方法默认是静态派发,不能被子类重写,编译器可以在编译时确定具体实现。 这样设计的原因有下面几点:

  • 明确性: extension表示添加新功能,override表示修改现有功能,两者分离,避免混淆。
  • 安全性:不允许重写 → 保证 extension 方法的稳定性。
  • 模块化:不用担心用户重写了自己模块extension中方法导致异常。
  • 良好实践:使用 extension 分离关注点。
class BaseClass {
    // 进入类的虚函数表
    func original() { print("Base original") }
}

extension BaseClass {
    // 不在虚函数表中!相当于直接是函数地址
    // 编译后的伪代码: 是生成一个全局函数
    // void String_extension_customMethod(String *self) {
    //     // 函数体
    // }
    func extensionMethod() { print("extension method") }
    
    // ❌ 不能在 extension 中重写原类方法
    // override func original() { }  // 编译错误
}

class SubClass: BaseClass {
    // ✅ 可以重写原类方法
    override func original() { print("SubClass original") }
    
    // ❌ 不能重写 extension 中的方法
    // override func extensionMethod() { }  // 编译错误
}

对 Objective-C 类的 extension

// Objective-C 类(如 UIView)
extension UIView {
    // 仍然是直接派发(在 Swift 中调用时)
    func swiftExtensionMethod() { }
    
    // 但通过 @objc 暴露给 Objective-C 时
    @objc func objcExposedMethod() { }  
    // Swift 内:直接派发
    // Objective-C 内:通过桥接,底层是消息派发
}

extension NSObject {
    @objc dynamic func specialMethod() { }
    // 这会强制使用消息派发
    // 可以被重写(因为是消息派发)
    // 但这是特殊情况,利用了 Objective-C 运行时
}

协议扩展extension

protocol Drawable {
    func draw()  // 协议要求
}

extension Drawable {
    func draw() {  // 默认实现
        print("默认绘制")
    }
    // 这是直接派发,但可以通过协议类型动态派发
}

class Circle: Drawable { }

let circle = Circle()
circle.draw()  // 直接派发:调用默认实现

let drawable: Drawable = circle
drawable.draw()  // 协议派发:通过协议见证表PWT(Protocol Witness Table)
// 内存布局
Circle 实例:
┌──────────┐
 数据字段  
├──────────┤
 PWT 指针   指向 Circle 的协议见证表
└──────────┘

CirclePWT:
┌──────────┐
 draw()     索引 0
├──────────┤
 resize()   索引 1
└──────────┘

2.3 Swift 类的虚函数表

对象实例内存布局:
┌───────────────────┐
│    对象头 (16字节)  │ ← 包含指向类对象的指针
├───────────────────┤
│  引用计数 (8字节)   │
├───────────────────┤
│  属性 name (8字节) │
├───────────────────┤
│  属性 age (8字节)  │
└───────────────────┘

类对象内存布局:
┌───────────────────┐
│   类信息 (元数据)   │
├───────────────────┤
│  虚函数表指针      │ → 指向虚函数表数组
├───────────────────┤
│  其他元数据...     │
└───────────────────┘

虚函数表结构:
┌───────────────────┐
│    makeSound()    │ ← 函数指针 [0]
├───────────────────┤
│       eat()       │ ← 函数指针 [1]
├───────────────────┤
│      sleep()      │ ← 函数指针 [2]
└───────────────────┘

虚函数表(V-Table)工作原理:

Dog 类的虚函数表(编译时根据顺序确定索引):
[0]: Dog.makeSound() 地址
[1]: Dog.otherMethod() 地址
...

调用 animal.makeSound():
1. 获取 animal 的虚函数表指针
2. 根据索引得到 makeSound 在表中的地址(编译时确定)
3. 跳转到对应地址执行

2.4 Swift 类方法的派发

类元数据结构:

┌─────────────────────┐
│    类型描述符        │ ← Metadata header
├─────────────────────┤
│    父类指针          │
├─────────────────────┤
│    实例变量偏移      │
├─────────────────────┤
│  ↓ 实例方法表指针    │ → 指向实例方法的虚函数表
├─────────────────────┤
│  ↓ 类方法表指针      │ → 指向类方法的独立表
├─────────────────────┤
│    协议列表指针      │
├─────────────────────┤
│    泛型信息...       │
└─────────────────────┘

实例方法表(虚函数表):
┌─────────────────────┐
│    instanceMethod1   │ ← 索引 0
├─────────────────────┤
│    instanceMethod2   │ ← 索引 1
└─────────────────────┘

类方法表:
┌─────────────────────┐
│     classMethod1     │ ← 索引 0  
├─────────────────────┤
│     classMethod2     │ ← 索引 1
└─────────────────────┘

派发方式

class MyClass {
    
    // 默认的表派发类方法
    class func classMethod() {  // 通过类的元数据进行派发
        print("类方法 - 表派发")
    }
    
    // 直接派发,不能被重写
    static func staticMethod() {  
        print("静态方法 - 直接派发")
    }
    
    // final class func 等价于 static func
    final class func alsoCannotOverride() { }
    
    @objc dynamic class func dynamicClassMethod() {
        print("类方法 - 消息派发")
    }
}

class AppConfig {
    // 存储在全局数据段
    static let appName = "MyApp"        // __TEXT 段(只读)
    static var launchCount = 0          // __DATA 段(读写)
    static let shared = AppConfig()     // 引用存储在全局,对象在堆上
    
    // 惰性静态属性
    static lazy var heavyResource = createHeavyResource()
}

/*
内存位置:
- appName: 编译时常量 → 代码段
- launchCount: 全局变量 → 数据段  
- shared: 引用在数据段,对象在堆上
- heavyResource: 第一次访问时初始化
*/

Part 3: 混合派发的危险实验

3.1 当 Swift 遇到 Swizzling

让我们看一个更完整的例子:

class MixedClass {
    // 情况1:纯 Swift
    func swiftMethod() { print("Swift Method") }
    
    // 情况2:暴露给 OC,但 Swift 内使用表派发
    @objc func exposedMethod() { print("Exposed Method") }
    
    // 情况3:完全动态
    @objc dynamic func dynamicMethod() { print("Dynamic Method") }
}

// 尝试 Swizzle
extension MixedClass {
    @objc dynamic func swizzled_swiftMethod() {
        print("Swizzled Swift")
        swizzled_swiftMethod()
    }
    
    @objc func swizzled_exposedMethod() {
        print("Swizzled Exposed")
        swizzled_exposedMethod()
    }
    
    @objc dynamic func swizzled_dynamicMethod() {
        print("Swizzled Dynamic")
        swizzled_dynamicMethod()
    }
    
    static func testAll() {
        let instance = MixedClass()
        
        print("=== 原始调用 ===")
        instance.swiftMethod()      // Swift Method
        instance.exposedMethod()    // Exposed Method
        instance.dynamicMethod()    // Dynamic Method
        
        // 尝试 Swizzle swiftMethod(缺少 dynamic)
        if let orig = class_getInstanceMethod(self, #selector(swiftMethod)),
           let swiz = class_getInstanceMethod(self, #selector(swizzled_swiftMethod)) {
            method_exchangeImplementations(orig, swiz)
        }
        
        // 尝试 Swizzle exposedMethod(只有 @objc)
        if let orig = class_getInstanceMethod(self, #selector(exposedMethod)),
           let swiz = class_getInstanceMethod(self, #selector(swizzled_exposedMethod)) {
            method_exchangeImplementations(orig, swiz)
        }
        
        // Swizzle dynamicMethod(正确方式)
        if let orig = class_getInstanceMethod(self, #selector(dynamicMethod)),
           let swiz = class_getInstanceMethod(self, #selector(swizzled_dynamicMethod)) {
            method_exchangeImplementations(orig, swiz)
        }
        
        print("\n=== Swizzle 后调用 ===")
        instance.swiftMethod()      // 还是 Swift Method ❌
        instance.exposedMethod()    // 还是 Exposed Method ❌  
        instance.dynamicMethod()    // Swizzled Dynamic ✅
        
        print("\n=== 通过 OC 运行时调用 ===")
        // 通过 performSelector 调用
        instance.perform(#selector(swiftMethod))      // 可能崩溃 💥
        instance.perform(#selector(exposedMethod))    // Swizzled Exposed ✅
        instance.perform(#selector(dynamicMethod))    // Swizzled Dynamic ✅
    }
}

3.2 为什么会这样?

内存布局解释:

当 Swift 编译一个类时:

  • 纯 Swift 方法 → 放入虚函数表
  • @objc 方法 → 生成桥接方法,同时放入虚函数表和 OC 方法列表(在Swift中调用未交换,OC中调用时已交换)
  • @objc dynamic 方法 → 直接放入 OC 方法列表

Swizzling 只影响 OC 方法列表,不影响虚函数表!

Part 4: 属性的 @objc dynamic

4.1 Swift中使用KVO

class Observable: NSObject {
    // 普通属性,不支持 KVO
    var name: String = ""
    
    // @objc dynamic 属性,支持 KVO
    @objc dynamic var age: Int = 0
    
    // 只有 @objc,不支持 KVO
    @objc var height: Double = 0.0
}

let obj = Observable()

// 尝试观察
// 运行时错误**Fatal error: Could not extract a String from KeyPath Swift.ReferenceWritableKeyPath<XXX.Observable, Swift.String>**
obj.observe(\.name, options: .new) { _, change in
    print("name changed: \(change.newValue ?? "nil")")
}  

obj.observe(\.age, options: .new) { _, change in
    print("age changed: \(change.newValue ?? 0)")
}  // ✅ 正常工作

obj.observe(\.height, options: .new) { _, change in
    print("height changed: \(change.newValue ?? 0)")
}  // 无法观察到变化

4.2 属性访问的派发方式

class PropertyTest {
    // 直接派发(编译时展开),会被内联
    var directProperty: Int {
        get { return _storage }
        set { _storage = newValue }
    }
    
    // 表派发(通过方法)
    var tableProperty: Int {
        get {
            print("getter 调用")
            return _storage
        }
        set {
            print("setter 调用")
            _storage = newValue
        }
    }
    
    // 消息派发(支持 KVO)
    @objc dynamic var messageProperty: Int {
        get { return _storage }
        set { _storage = newValue }
    }
    
    private var _storage: Int = 0
}

// @objc dynamic 属性会生成:
// - (NSInteger)messageProperty;
// - (void)setMessageProperty:(NSInteger)value;
// 这些是真正的 Objective-C 方法

4.3 属性观察器的有趣现象

class Observed: NSObject {
    @objc dynamic var value: Int = 0 {
        didSet {
            print("value 从 \(oldValue) 变为 \(value)")
        }
    }
    
    // 测试 KVO 和 didSet 的交互
    func test() {
        self.value = 10  // 触发 didSet
        
        // 通过 KVC 设置
        self.setValue(20, forKey: "value")  // 也会触发 didSet ✅
    }
}

// 为什么能工作?
// @objc dynamic 属性生成的 setter 会:
// 1. 调用 willChangeValueForKey
// 2. 设置新值
// 3. 调用 didSet(Swift 注入的代码)
// 4. 调用 didChangeValueForKey(触发 KVO)

Part 5: 派发方式的确定规则

5.1 决策树

// Swift 编译器决定派发方式的逻辑:
func determineDispatch(for method: Method) -> DispatchType {
    if method.isFinal || type.isFinal || type.isStruct {
        return .direct      // 1. final 或 struct → 直接派发
    }
    
    if method.isDynamic {
        return .message     // 2. dynamic → 消息派发
    }
    
    if method.isObjC {
        // @objc 但不 dynamic:桥接方法
        return .table       // 3. 在 Swift 内使用表派发
    }
    
    if method.isInExtension && !type.isObjCClass {
        return .direct      // 4. 非 OC 类的扩展 → 直接派发
    }
    
    return .table           // 5. 默认 → 表派发
}

5.2 特殊情况

// 1. 协议要求
protocol MyProtocol {
    func requiredMethod()   // 表派发(通过协议见证表)
}

// 2. 泛型约束
func genericFunc<T: MyProtocol>(_ obj: T) {
    obj.requiredMethod()    // 静态派发(编译时特化)
}

// 3. @_dynamicReplacement
class Replaceable {
    dynamic func original() { print("Original") }
}

extension Replaceable {
    @_dynamicReplacement(for: original)
    func replacement() { print("Replacement") }
}
// Swift 5 引入的官方 "Swizzling"

Part 6: 性能影响与优化

优化建议

// ❌ 避免在性能关键路径使用 dynamic
class Cache {
    @objc dynamic var data: [String: Any] = [:]  // 每次访问都有消息派发开销
    
    func expensiveOperation() {
        for _ in 0..<10000 {
            _ = data["key"]  // 慢!
        }
    }
}

// ✅ 优化方案
class OptimizedCache {
    private var _data: [String: Any] = [:]
    
    var data: [String: Any] {
        get { return _data }
        set { _data = newValue }
    }
    
    @objc dynamic var observableData: [String: Any] {
        get { return _data }
        set { _data = newValue }
    }
    
    func expensiveOperation() {
        let localData = data  // 一次读取
        for _ in 0..<10000 {
            _ = localData["key"]  // 快!
        }
    }
}

Part 7: 实际应用指南

7.1 何时使用何种派发?

// 指南:
class MyClass {
    // ✅ 使用直接派发:
    final func utilityMethod() { }  // 工具方法,不重写
    private func helper() { }       // 私有方法
    
    // ✅ 使用表派发(默认):
    func businessLogic() { }        // 业务逻辑,可能被重写
    open func publicAPI() { }       // 公开 API
    
    // ⚠️ 谨慎使用消息派发:
    @objc dynamic func kvoProperty() { }  // 需要 KVO
    @objc dynamic func swizzleMe() { }    // 需要 Method Swizzling
    
    // ❌ 避免混用:
    @objc func confusingMethod() { }  // 既不是鱼也不是熊掌
    // 在 Swift 中是表派发,在 OC 中是消息派发
    // 可能导致不一致的行为
}

7.2 安全 Swizzling 的最佳实践

class SafeSwizzler {
    /// 安全的 Method Swizzling
    static func swizzle(_ type: AnyClass,
                       original: Selector,
                       swizzled: Selector,
                       isClassMethod: Bool = false) throws {
        
        // 1. 获取方法
        let getMethod = isClassMethod ? class_getClassMethod : class_getInstanceMethod
        guard let originalMethod = getMethod(type, original),
              let swizzledMethod = getMethod(type, swizzled) else {
            throw SwizzleError.methodNotFound
        }
        
        // 2. 检查是否已经是消息派发
        let originalEncoding = method_getTypeEncoding(originalMethod)
        if originalEncoding == nil {
            throw SwizzleError.notMessageDispatch
        }
        
        // 3. 检查是否已经 Swizzled
        if alreadySwizzled {
            throw SwizzleError.alreadySwizzled
        }
        
        // 4. 执行交换
        method_exchangeImplementations(originalMethod, swizzledMethod)
    }
    
    enum SwizzleError: Error {
        case methodNotFound
        case notMessageDispatch
        case alreadySwizzled
    }
}

// 使用
extension UIViewController {
    @objc dynamic func safe_viewDidLoad() {
        print("Safe tracking")
        safe_viewDidLoad()
    }
    
    static func enableSafeTracking() {
        do {
            try SafeSwizzler.swizzle(
                UIViewController.self,
                original: #selector(viewDidLoad),
                swizzled: #selector(safe_viewDidLoad)
            )
            print("✅ Safe swizzling 成功")
        } catch {
            print("❌ Swizzling 失败: \(error)")
        }
    }
}

总结

关键要点

  1. Swift 有三种派发方式

    • 直接派发:最快,用于 final、结构体等
    • 表派发:默认,通过虚函数表
    • 消息派发:最慢,但支持运行时特性
  2. @objc vs dynamic

    • @objc:让 Swift 方法对 OC 可见,但 Swift 内仍用表派发
    • dynamic:强制使用消息派发
    • @objc dynamic:OC 可见 + 消息派发
  3. Swizzling 的真相

    • 只能交换消息派发的方法
    • 交换表派发方法会导致 Swift 和 OC 行为不一致
    • 这是很多 Swizzling bug 的根源
  4. 性能影响

    • 消息派发比直接派发慢 4-5 倍
    • 避免在性能关键路径使用 dynamic
    • 合理使用 final 优化性能

哲学思考

Swift 的派发机制体现了语言设计的平衡艺术:

  • 安全 vs 灵活:表派发保证安全,消息派发提供灵活
  • 性能 vs 功能:直接派发优化性能,动态派发启用高级功能
  • Swift vs Objective-C:两种运行时模型的巧妙融合

理解这些机制,你就能:

  • 写出更高效的 Swift 代码
  • 安全地使用运行时特性
  • 避免诡异的 Swizzling bug
  • 更好地理解 Swift 的设计哲学

记住:强大的能力伴随着巨大的责任。动态派发给了你 hook 系统方法的能力,但也可能带来难以调试的问题。使用时务必谨慎!

“死了么”App荣登付费榜第一名!

背景 2026年初的App Store付费榜,突然杀出一匹“黑马”——一款名为 「“死了么 - 官方正版”」 的产品,以8元付费下载的模式,毫无征兆地登顶付费榜单榜首,成为今年首个现象级爆款。对于常年

AppStore卡审依旧存在,预计下周将逐渐恢复常态!

背景

圣诞节🎄虽然结束了,后劲儿依旧在。最直观的感受就是AppStore审核节奏还未恢复正常。依然存在审核时间较久或等待审核时间过长的问题。

举一个直观的例子🌰:

一座5层高的商场,每层都预备了洗手间🚾。正常情况下,足够满足整座商城客流量的需求。但是赶上了节假日高峰,并且只有3层洗手间可用。那么在常态客流量不变的情况也已经拥挤,更不要说节假日高峰期。

就第三方上架&更新趋势来看,AppStore审核节奏也将逐步正常。

非必要迭代

如果不是遇到重大线上问题或重大功能迭代,建议不更新或不上新包。避免正常产品遭遇卡审状态,导致难以定位问题或者审核员摆烂直接一手4.3a。

毕竟AppStore审核团队,刚刚经历了年关肯定积压了大量待审核的产品,多少也有些烦躁。(PS:单纯从心理角度来讲

新包、新账号和新代码,“三新原则”基本上叠满了卡审buffer。【特指中国大陆的开发者,海外账号亲测影响不大。】

重大更新

对于产品有着节前活动或市场战略布局的产品,那么也不用担心。在AppStore依然存在便捷通道:即加急审核!

常规产品,不必担心,这是官方提供的合理渠道,确实保障开发者的紧急需求【AppStore中的急诊室】。

遵守规则,方得长治久安,最后祝大家大吉大利,今晚过审!

相关推荐

# 苹果开发者续费大坑及成功续费方案!亲测有效

# AppStore敏感词排查手册,多维度分析Guideline 2.3.1隐藏功能,轻松过审。

# 如何主动提防苹果3.2f的进攻,自查防御手册(代码篇)

# 如何主动提防苹果3.2f的进攻,自查防御手册(ASO篇)

# 苹果加急审核是“绿色通道”还是“死亡陷阱”?

# 苹果开发者邮箱,突然收到11.2通知严重么?

# 不想被苹果卡审最好错开这两个提审时间

# 手撕苹果审核4.3是代码问题还是设计问题?

# 有幸和Appstore审核人员进行了一场视频会议特此记录。

2026 年 Expo + React Native 项目接入微信分享完整指南

2026 年 Expo + React Native 项目接入微信分享完整指南

本文基于 Expo SDK 54 + React Native 0.81 + react-native-wechat-lib 1.1.27 的实战经验,详细记录了在 Expo 管理的 React Native 项目中接入微信分享功能的完整流程和踩坑记录。

前言

在 React Native 生态中,react-native-wechat-lib 是目前最常用的微信 SDK 封装库。但由于该库更新较慢,加上 Expo 的特殊性,接入过程中会遇到不少坑。本文将分享我们在生产项目中的完整接入方案。

技术栈

  • Expo SDK: 54.0.30
  • React Native: 0.81.5
  • react-native-wechat-lib: 1.1.27
  • 构建方式: EAS Build

整体流程

准备工作 → 安装依赖 → 创建 Expo 插件 → 配置 app.config.js → 
编写 JS 服务层 → 服务器配置 → 微信开放平台配置 → 构建测试

第一步:准备工作

1.1 微信开放平台配置

  1. 登录 微信开放平台
  2. 创建移动应用,获取 AppID
  3. 配置 iOS 应用信息:
    • Bundle ID: com.yourapp
    • Universal Link: https://yourdomain.com/open/

1.2 Apple Developer 配置

  1. 获取 Team ID(格式如 A1B2C3D4E5
  2. 确认 Bundle ID 与微信开放平台一致

第二步:安装依赖

npm install react-native-wechat-lib@1.1.27

⚠️ 注意:在 Expo 管理的项目中,不需要手动执行 pod install,EAS Build 会自动处理。

第三步:创建 Expo Config Plugin

由于 Expo 管理原生代码,我们需要通过 Config Plugin 来配置微信 SDK 所需的原生设置。

创建 plugins/withWechat.js

const { withInfoPlist, withAndroidManifest } = require("expo/config-plugins");

/**
 * 微信 SDK Expo Config Plugin
 * 自动配置 iOS 和 Android 的微信相关设置
 */
function withWechat(config, { appId, universalLink }) {
  if (!appId) {
    throw new Error("withWechat: appId is required");
  }

  // iOS 配置
  config = withInfoPlist(config, (config) => {
    // 添加微信 URL Scheme
    const urlTypes = config.modResults.CFBundleURLTypes || [];
    const wechatScheme = {
      CFBundleURLSchemes: [appId],
      CFBundleURLName: "wechat",
    };

    const hasWechatScheme = urlTypes.some(
      (type) =>
        type.CFBundleURLSchemes &&
        type.CFBundleURLSchemes.includes(appId)
    );

    if (!hasWechatScheme) {
      urlTypes.push(wechatScheme);
    }
    config.modResults.CFBundleURLTypes = urlTypes;

    // 添加 LSApplicationQueriesSchemes
    const queriesSchemes = config.modResults.LSApplicationQueriesSchemes || [];
    const wechatSchemes = ["weixin", "weixinULAPI"];
    wechatSchemes.forEach((scheme) => {
      if (!queriesSchemes.includes(scheme)) {
        queriesSchemes.push(scheme);
      }
    });
    config.modResults.LSApplicationQueriesSchemes = queriesSchemes;

    return config;
  });

  // Android 配置
  config = withAndroidManifest(config, (config) => {
    const mainApplication = config.modResults.manifest.application?.[0];
    if (!mainApplication) return config;

    const packageName = config.android?.package || "com.yourapp";
    const activities = mainApplication.activity || [];
    const wxActivityName = `${packageName}.wxapi.WXEntryActivity`;

    const hasWxActivity = activities.some(
      (activity) => activity.$?.["android:name"] === wxActivityName
    );

    if (!hasWxActivity) {
      activities.push({
        $: {
          "android:name": wxActivityName,
          "android:exported": "true",
          "android:launchMode": "singleTask",
          "android:taskAffinity": packageName,
          "android:theme": "@android:style/Theme.Translucent.NoTitleBar",
        },
      });
    }

    mainApplication.activity = activities;
    return config;
  });

  return config;
}

module.exports = withWechat;

第四步:配置 app.config.js

module.exports = {
  expo: {
    name: "你的应用名",
    slug: "your-app",
    version: "1.0.0",
    
    extra: {
      wechatAppId: "wx你的AppID", // 微信 AppID
    },
    
    ios: {
      bundleIdentifier: "com.yourapp",
      associatedDomains: [
        "applinks:yourdomain.com",
        "webcredentials:yourdomain.com",
      ],
      infoPlist: {
        LSApplicationQueriesSchemes: ["weixin", "weixinULAPI", "wechat"],
      },
    },
    
    android: {
      package: "com.yourapp",
    },
    
    plugins: [
      [
        "./plugins/withWechat",
        {
          appId: "wx你的AppID",
          universalLink: "https://yourdomain.com/open/",
        },
      ],
    ],
  },
};

第五步:编写微信服务层

创建 src/services/wechatService.ts

import { Platform, Alert } from "react-native";
import Constants from "expo-constants";

// 从 Expo 配置中获取微信 AppID
const WECHAT_APP_ID = Constants.expoConfig?.extra?.wechatAppId || "";

// 动态加载微信 SDK
let WeChat: any = null;
let sdkLoadAttempted = false;

const getWechatSDK = () => {
  if (sdkLoadAttempted) return WeChat;
  sdkLoadAttempted = true;
  
  if (Platform.OS === "web") {
    return null;
  }
  
  try {
    const module = require("react-native-wechat-lib");
    WeChat = module.default || module;
    
    if (!WeChat || typeof WeChat.registerApp !== "function") {
      WeChat = null;
    }
    
    return WeChat;
  } catch (error) {
    console.warn("微信 SDK 加载失败:", error);
    return null;
  }
};

class WechatService {
  private isRegistered = false;

  // 检查 SDK 是否可用
  isAvailable(): boolean {
    if (Platform.OS === "web") return false;
    const sdk = getWechatSDK();
    return sdk !== null && typeof sdk.registerApp === "function";
  }

  // 注册微信 SDK
  async register(): Promise<boolean> {
    if (this.isRegistered) return true;
    
    const sdk = getWechatSDK();
    if (!sdk) return false;
    
    try {
      const result = await sdk.registerApp(WECHAT_APP_ID);
      this.isRegistered = result;
      return result;
    } catch (error) {
      console.error("微信 SDK 注册失败:", error);
      return false;
    }
  }

  // 检查微信是否已安装
  async isWechatInstalled(): Promise<boolean> {
    const sdk = getWechatSDK();
    if (!sdk) return false;
    
    try {
      return await sdk.isWXAppInstalled();
    } catch (error) {
      return false;
    }
  }

  // 分享网页到微信
  async shareWebpage(params: {
    title: string;
    description: string;
    thumbImageUrl?: string;
    webpageUrl: string;
    scene?: "session" | "timeline" | "favorite";
  }): Promise<{ success: boolean; message: string }> {
    
    if (!this.isAvailable()) {
      return { 
        success: false, 
        message: Platform.OS === "web" 
          ? "Web 端暂不支持微信分享" 
          : "微信分享功能需要在正式构建版本中使用"
      };
    }

    try {
      const registered = await this.register();
      if (!registered) {
        return { success: false, message: "微信 SDK 初始化失败" };
      }

      const isInstalled = await this.isWechatInstalled();
      if (!isInstalled) {
        return { success: false, message: "请先安装微信" };
      }

      const sceneMap = {
        session: 0,   // 聊天界面
        timeline: 1,  // 朋友圈
        favorite: 2,  // 收藏
      };

      const sdk = getWechatSDK();
      await sdk.shareWebpage({
        title: params.title,
        description: params.description,
        thumbImageUrl: params.thumbImageUrl || "",
        webpageUrl: params.webpageUrl,
        scene: sceneMap[params.scene || "session"],
      });

      return { success: true, message: "分享成功" };
    } catch (error: any) {
      if (error?.errCode === -2) {
        return { success: false, message: "已取消分享" };
      }
      return { success: false, message: error?.message || "分享失败" };
    }
  }

  // 分享图片到微信
  async shareImage(params: {
    imageUrl?: string;
    imageBase64?: string;
    scene?: "session" | "timeline" | "favorite";
  }): Promise<{ success: boolean; message: string }> {
    if (!this.isAvailable()) {
      return { success: false, message: "微信分享不可用" };
    }

    try {
      await this.register();
      
      const isInstalled = await this.isWechatInstalled();
      if (!isInstalled) {
        return { success: false, message: "请先安装微信" };
      }

      const sceneMap = { session: 0, timeline: 1, favorite: 2 };
      const sdk = getWechatSDK();
      
      await sdk.shareImage({
        imageUrl: params.imageBase64 || params.imageUrl,
        scene: sceneMap[params.scene || "session"],
      });

      return { success: true, message: "分享成功" };
    } catch (error: any) {
      if (error?.errCode === -2) {
        return { success: false, message: "已取消分享" };
      }
      return { success: false, message: "分享失败" };
    }
  }
}

export const wechatService = new WechatService();

第六步:服务器配置 (Universal Link)

在你的服务器上创建 apple-app-site-association 文件。

文件路径

https://yourdomain.com/.well-known/apple-app-site-association

文件内容

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appIDs": ["TEAMID.com.yourapp"],
        "components": [
          { "/": "/open/*" },
          { "/": "/topic/*" }
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["TEAMID.com.yourapp"]
  }
}

⚠️ 将 TEAMID 替换为你的 Apple Team ID,com.yourapp 替换为你的 Bundle ID。

服务器配置要求

  1. 必须通过 HTTPS 访问
  2. Content-Type 应为 application/json
  3. 文件名不能有 .json 后缀
  4. 不能有重定向

Nginx 配置示例

location /.well-known/apple-app-site-association {
    default_type application/json;
}

第七步:在组件中使用

import React from "react";
import { Button, Alert } from "react-native";
import { wechatService } from "@/services/wechatService";

export function ShareButton() {
  const handleShare = async () => {
    const result = await wechatService.shareWebpage({
      title: "分享标题",
      description: "分享描述",
      thumbImageUrl: "https://example.com/thumb.jpg",
      webpageUrl: "https://example.com/share-page",
      scene: "session", // 或 "timeline" 分享到朋友圈
    });

    if (result.success) {
      Alert.alert("成功", "分享成功");
    } else {
      Alert.alert("提示", result.message);
    }
  };

  return <Button title="分享到微信" onPress={handleShare} />;
}

第八步:构建和测试

使用 EAS Build

# 构建 iOS 生产版本
eas build -p ios --profile production

# 构建并自动提交到 TestFlight
eas build -p ios --profile production --auto-submit

测试注意事项

  1. Expo Go 不支持:微信 SDK 是原生模块,必须使用 EAS Build 构建的版本测试
  2. 重启手机:安装新版本后建议重启手机,让 iOS 刷新 Associated Domains 缓存
  3. 验证 Universal Link:访问 https://app-site-association.cdn-apple.com/a/v1/yourdomain.com 确认 Apple 已缓存配置

常见问题排查

问题 1:分享时微信没有被唤起

可能原因:

  • Universal Link 配置不一致(微信开放平台、App 代码、服务器三端必须完全一致)
  • apple-app-site-association 文件内容错误或无法访问
  • Apple 还未缓存你的配置

排查步骤:

  1. 确认三端域名完全一致(注意 www 和非 www 的区别)
  2. 直接访问 https://yourdomain.com/.well-known/apple-app-site-association 确认可以下载
  3. 检查 Apple CDN 缓存:https://app-site-association.cdn-apple.com/a/v1/yourdomain.com

问题 2:SDK 注册失败

可能原因:

  • AppID 配置错误
  • 在 Expo Go 中运行(不支持)

解决方案:

  • 确认 app.config.js 中的 AppID 与微信开放平台一致
  • 使用 EAS Build 构建的版本测试

问题 3:提示"请先安装微信"

可能原因:

  • LSApplicationQueriesSchemes 未正确配置

解决方案: 确认 app.config.js 中包含:

infoPlist: {
  LSApplicationQueriesSchemes: ["weixin", "weixinULAPI", "wechat"],
}

调试技巧

在开发阶段,可以添加调试弹窗来追踪问题:

const DEBUG_MODE = true;

const debugAlert = (title: string, message: string) => {
  if (DEBUG_MODE) {
    Alert.alert(`[调试] ${title}`, message);
  }
};

// 在关键步骤添加调试
debugAlert("开始分享", `AppID: ${WECHAT_APP_ID}`);
debugAlert("注册结果", `registered: ${registered}`);
debugAlert("微信安装检查", `isInstalled: ${isInstalled}`);

总结

在 Expo 项目中接入微信分享的关键点:

  1. 使用 Config Plugin 配置原生设置,而不是手动修改原生代码
  2. 三端配置一致 是成功的关键(微信开放平台、App、服务器)
  3. Universal Link 配置正确且可访问
  4. 必须使用 EAS Build 构建的版本测试,Expo Go 不支持原生模块

希望这篇文章能帮助你顺利接入微信分享功能!如有问题欢迎评论区交流。


参考资料:

Luban 2 Flutter:一行代码在 Flutter 开发中实现图片压缩功能

Luban 2 Flutter —— 高效简洁的 Flutter 图片压缩插件,像素级还原微信朋友圈压缩策略。

📑 目录

📖 项目描述

开源地址:Gitee | Github

目前做 App 开发总绕不开图片这个元素。但是随着手机拍照分辨率的提升,图片的压缩成为一个很重要的问题。单纯对图片进行裁切,压缩已经有很多文章介绍。但是裁切成多少,压缩成多少却很难控制好,裁切过头图片太小,质量压缩过头则显示效果太差。

于是自然想到 App 巨头"微信"会是怎么处理,Luban(鲁班)就是通过在微信朋友圈发送近100张不同分辨率图片,对比原图与微信压缩后的图片逆向推算出来的压缩算法。

因为是逆向推算,效果还没法跟微信一模一样,但是已经很接近微信朋友圈压缩后的效果,具体看以下对比!

本库是 LubanFlutter 版本,使用 TurboJPEG 进行高性能图片压缩,提供简洁易用的 API 和接近微信朋友圈的压缩效果。

📊 效果与对比

图片类型 原图(分辨率, 大小) Luban(分辨率, 大小) Wechat(分辨率, 大小)
标准拍照 3024×4032, 5.10MB 1440×1920, 305KB 1440×1920, 303KB
高清大图 4000×6000, 12.10MB 1440×2160, 318KB 1440×2160, 305KB
2K 截图 1440×3200, 2.10MB 1440×3200, 148KB 1440×3200, 256KB
超长记录 1242×22080, 6.10MB 758×13490, 290KB 744×13129, 256KB
全景横图 12000×5000, 8.10MB 1440×600, 126KB 1440×600, 123KB
设计原稿 6000×6000, 6.90MB 1440×1440, 263KB 1440×1440, 279KB

🔬 核心算法特性

本库采用自适应统一图像压缩算法 (Adaptive Unified Image Compression),通过原图的分辨率特征,动态应用差异化策略,实现画质与体积的最优平衡。

智能分辨率决策

  • 高清基准 (1440p):默认以 1440px 作为短边基准,确保在现代 2K/4K 屏幕上的视觉清晰度
  • 全景墙策略:自动识别超大全景图(长边 >10800px),锁定长边为 1440px,保留完整视野
  • 超大像素陷阱:对超过 4096万像素的超高像素图自动执行 1/4 降采样处理
  • 长图内存保护:针对超长截图建立 10.24MP 像素上限,通过等比缩放防止 OOM

自适应比特率控制

  • 极小图 (<0.5MP):几乎不进行有损压缩,防止压缩伪影
  • 高频信息图 (0.5-1MP):提高编码质量,补偿分辨率损失
  • 标准图片 (1-3MP):应用平衡系数,对标主流社交软件体验
  • 超大图/长图 (>3MP):应用高压缩率,显著减少体积

健壮性保障

  • 膨胀回退:压缩后体积大于原图时,自动透传原图,确保绝不"负优化"
  • 输入防御:妥善处理极端分辨率输入(0、负数、1px 等),防止崩溃

📦 安装

pubspec.yaml 文件中添加依赖:

dependencies:
  luban: ^2.0.1

然后运行:

flutter pub get

💻 使用

压缩单张图片

使用 File 对象

import 'dart:io';
import 'package:luban/luban.dart';

Future<void> compressImage() async {
  final file = File('/path/to/image.jpg');
  final result = await Luban.compress(file);
  
  if (result.isSuccess) {
    final compressionResult = result.value;
    print('压缩完成');
    print('原图大小: ${compressionResult.originalSizeKb} KB');
    print('压缩后大小: ${compressionResult.compressedSizeKb} KB');
    print('压缩率: ${(compressionResult.compressionRatio * 100).toStringAsFixed(1)}%');
    print('输出文件: ${compressionResult.file.path}');
  } else {
    print('压缩失败: ${result.error}');
  }
}

使用字符串路径

import 'package:luban/luban.dart';

Future<void> compressImage() async {
  final result = await Luban.compressPath('/path/to/image.jpg');
  
  result.fold(
    (error) => print('压缩失败: $error'),
    (compressionResult) {
      print('压缩完成,大小: ${compressionResult.compressedSizeKb} KB');
      print('输出文件: ${compressionResult.file.path}');
    },
  );
}

指定输出文件

import 'dart:io';
import 'package:luban/luban.dart';

Future<void> compressImage() async {
  final inputFile = File('/path/to/image.jpg');
  final outputFile = File('/path/to/output/compressed.jpg');
  
  final result = await Luban.compressToFile(inputFile, outputFile);
  
  if (result.isSuccess) {
    final compressionResult = result.value;
    print('压缩完成,文件已保存到: ${compressionResult.file.path}');
  }
}

指定输出目录

import 'dart:io';
import 'package:luban/luban.dart';

Future<void> compressImage() async {
  final inputFile = File('/path/to/image.jpg');
  final outputDir = Directory('/path/to/output');
  
  final result = await Luban.compress(inputFile, outputDir: outputDir);
  
  if (result.isSuccess) {
    final compressionResult = result.value;
    print('压缩完成,文件已保存到: ${compressionResult.file.path}');
  }
}

批量压缩图片

批量压缩返回 Result<BatchCompressionResult>,需要先检查成功或失败状态,然后访问 BatchCompressionResult 获取所有图片的压缩结果。

使用文件列表

import 'dart:io';
import 'package:luban/luban.dart';

Future<void> compressBatchImages() async {
  final files = [
    File('/path/to/image1.jpg'),
    File('/path/to/image2.jpg'),
    File('/path/to/image3.jpg'),
  ];
  
  final result = await Luban.compressBatch(files);
  
  if (result.isSuccess) {
    final batchResult = result.value;
    print('批量压缩完成');
    print('总数: ${batchResult.total}');
    print('成功: ${batchResult.successCount}');
    print('失败: ${batchResult.failureCount}');
    
    for (final item in batchResult.items) {
      if (item.isSuccess) {
        final compressionResult = item.result.value;
        print('${item.originalPath}: ${compressionResult.compressedSizeKb} KB');
      } else {
        print('${item.originalPath}: 压缩失败 - ${item.result.error}');
      }
    }
  } else {
    print('批量压缩失败: ${result.error}');
  }
}

使用路径列表

import 'package:luban/luban.dart';

Future<void> compressBatchImages() async {
  final paths = [
    '/path/to/image1.jpg',
    '/path/to/image2.jpg',
    '/path/to/image3.jpg',
  ];
  
  final result = await Luban.compressBatchPaths(paths);
  
  result.fold(
    (error) => print('批量压缩失败: $error'),
    (batchResult) {
      print('批量压缩完成,成功 ${batchResult.successCount}/${batchResult.total} 张');
      
      for (final compressionResult in batchResult.successfulResults) {
        print('${compressionResult.file.path}: ${compressionResult.compressedSizeKb} KB');
      }
    },
  );
}

批量压缩并指定输出目录

import 'dart:io';
import 'package:luban/luban.dart';

Future<void> compressBatchImages() async {
  final files = [
    File('/path/to/image1.jpg'),
    File('/path/to/image2.jpg'),
  ];
  final outputDir = Directory('/path/to/output');
  
  final result = await Luban.compressBatch(files, outputDir: outputDir);
  
  if (result.isSuccess) {
    final batchResult = result.value;
    print('批量压缩完成,成功 ${batchResult.successCount} 张');
    
    for (final compressionResult in batchResult.successfulResults) {
      print('压缩文件: ${compressionResult.file.path}');
    }
  } else {
    print('批量压缩失败: ${result.error}');
  }
}

iOS应用(App)生命周期、视图控制器(UIViewController)生命周期和视图(UIView)生命周期

清晰的理解它们能帮你更好地管理应用状态和资源。

一、iOS 应用(App)生命周期

应用生命周期描述了 App 从启动到终止的整个过程,由UIApplicationDelegate(应用代理)来管理。

核心阶段与代理方法(按执行顺序)

import UIKit

@UIApplicationMain

class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    // 1. App启动完成(最核心的入口)
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        print("应用启动完成 - didFinishLaunchingWithOptions")

        // 通常在这里初始化根视图控制器、配置全局设置等

        return true

    }


    // 2. App即将进入前台(还未激活,可做界面刷新)
    func applicationWillEnterForeground(_ application: UIApplication) {
    
        print("即将进入前台 - applicationWillEnterForeground")

    }


    // 3. App已进入前台并激活(用户可交互)
    func applicationDidBecomeActive(_ application: UIApplication) {

        print("已激活 - applicationDidBecomeActive")

        // 恢复定时器、重新开始播放音频、刷新数据等

    }

    // 4. App即将进入后台(用户按Home键/切换App)
    func applicationWillResignActive(_ application: UIApplication) {

        print("即将失活 - applicationWillResignActive")

        // 暂停定时器、保存临时数据、暂停音频播放等

    }


    // 5. App已进入后台
    func applicationDidEnterBackground(_ application: UIApplication) {

        print("已进入后台 - applicationDidEnterBackground")

        // 持久化数据、释放不必要的资源(有大约5秒时间,耗时操作需申请后台任务)

    }

    // 6. App即将终止(仅在后台时可能触发,如系统回收内存)
    func applicationWillTerminate(_ application: UIApplication) {

        print("即将终止 - applicationWillTerminate")

        // 最终的资源清理、数据保存

    }

}

关键说明

  • 启动流程:用户点击 App 图标 → 系统加载可执行文件 → 调用didFinishLaunchingWithOptions → 显示界面 → 进入活跃状态。
  • 后台与前台切换:活跃 → 失活(WillResignActive)→ 后台(DidEnterBackground)→ 前台(WillEnterForeground)→ 活跃(DidBecomeActive)。
  • 终止:后台状态下系统回收内存,触发applicationWillTerminate(若 App 在前台,直接终止,不触发此方法)。

二、UIViewController 生命周期

视图控制器是管理 UIView 的核心,其生命周期围绕视图的创建、显示、隐藏、销毁展开,是 iOS 开发中最常接触的生命周期。

核心方法(按执行顺序)

import UIKit

class ViewController: UIViewController {

    // 1. 初始化(创建VC对象)
    init?(coder: NSCoder) {
        super.init(coder: coder)
        print("1. 初始化 - init")
        // 初始化非UI相关的属性
    }

    // 2. 加载视图(首次访问view属性时触发)
    override func loadView() {
        super.loadView()
        print("2. 加载视图 - loadView")
        // 手动创建view(若不重写,系统会加载storyboard/xib的view)
        self.view = UIView(frame: UIScreen.main.bounds)
        self.view.backgroundColor = .white
    }

    // 3. 视图加载完成(view已创建完成)
    override func viewDidLoad() {
        super.viewDidLoad()
        print("3. 视图加载完成 - viewDidLoad")
        // 初始化UI控件、绑定数据、添加监听(只执行一次)
    }

    // 4. 视图即将布局子视图(view的bounds变化时触发,如旋转屏幕)
    override func viewWillLayoutSubviews() {
        super.viewWillLayoutSubviews()
        print("4. 视图即将布局子视图 - viewWillLayoutSubviews")
        // 调整控件布局(执行多次)
    }

    // 5. 视图已布局子视图
    override func viewDidLayoutSubviews() {
        super.viewDidLayoutSubviews()
        print("5. 视图已布局子视图 - viewDidLayoutSubviews")
        // 获取控件最终的frame(执行多次)
    }

    // 6. 视图即将显示在屏幕上(每次显示都触发,如push/pop后重新显示)
    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        print("6. 视图即将显示 - viewWillAppear")
        // 刷新数据、开始动画、注册通知等
    }

    // 7. 视图已显示在屏幕上
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        print("7. 视图已显示 - viewDidAppear")
        // 启动定时器、请求网络数据、播放视频等
    }

    // 8. 视图即将从屏幕上消失
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        print("8. 视图即将消失 - viewWillDisappear")
        // 暂停动画、移除通知、保存数据等
    }

    // 9. 视图已从屏幕上消失
    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        print("9. 视图已消失 - viewDidDisappear")
        // 释放不必要的资源(如图片缓存)
    }

    // 10. 内存警告(系统内存不足时触发)
    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        print("10. 内存警告 - didReceiveMemoryWarning")
        // 释放缓存、非必要的视图等
    }

    // 11. 视图控制器销毁(deinit)
    deinit {
        print("11. 视图控制器销毁 - deinit")
        // 最终的资源释放(如移除监听、取消网络请求)
    }
}

关键说明

  • 核心流程:初始化 → 加载视图 → 视图加载完成 → 布局子视图 → 即将显示 → 已显示 → 即将消失 → 已消失 → 销毁。
  • viewDidLoad:只执行一次,适合做一次性初始化;viewWillAppear/viewDidAppear:每次显示都执行,适合刷新动态数据。
  • 内存警告didReceiveMemoryWarning中需主动释放非必要资源,避免 App 被系统杀死。
  • deinit:只有当 VC 的引用计数为 0 时才会触发,需确保无循环引用(如闭包未捕获 self 为 weak/unowned)。

三、UIView 生命周期

UIView 的生命周期依附于视图控制器,核心是 “创建 - 布局 - 绘制 - 销毁”,重点关注布局和绘制相关方法。

核心阶段与方法

import UIKit

class CustomView: UIView {

    // 1. 初始化(创建View)
    override init(frame: CGRect) {
        super.init(frame: frame)
        print("1. View初始化 - init(frame:)")
        // 设置默认属性(如背景色、圆角)
        self.backgroundColor = .lightGray
    }

    required init?(coder: NSCoder) {
        super.init(coder: coder)
        print("1. View初始化 - init(coder:)")
    }

    // 2. 准备布局(iOS 6+,替代autoresizingMask)
    override func prepareForLayout() {
        super.prepareForLayout()
        print("2. 准备布局 - prepareForLayout")
        // 布局前的准备工作(如设置约束优先级)
    }

    // 3. 布局子视图(bounds变化时触发,如frame、center修改)
    override func layoutSubviews() {
        super.layoutSubviews()
        print("3. 布局子视图 - layoutSubviews")
        // 手动调整子视图frame(若不用AutoLayout)
        for subview in self.subviews {
            subview.center = self.center
        }
    }

    // 4. 绘制内容(首次显示/setNeedsDisplay()触发)
    override func draw(_ rect: CGRect) {
        super.draw(rect)
        print("4. 绘制内容 - draw(_:)")
        // 手动绘制图形(如绘制线条、文字)
        let context = UIGraphicsGetCurrentContext()
        context?.setStrokeColor(UIColor.red.cgColor)
        context?.stroke(CGRect(x: 10, y: 10, width: 100, height: 100))
    }

    // 5. 即将添加到父视图
    override func willMove(toSuperview newSuperview: UIView?) {
        super.willMove(toSuperview: newSuperview)
        print("5. 即将添加到父视图 - willMove(toSuperview:)")
        // 父视图变化前的处理
    }

    // 6. 已添加到父视图
    override func didMoveToSuperview() {
        super.didMoveToSuperview()
        print("6. 已添加到父视图 - didMoveToSuperview")
        // 父视图变化后的处理(如根据父视图调整自身大小)
    }

    // 7. 即将添加到窗口
    override func willMove(toWindow newWindow: UIWindow?) {
        super.willMove(toWindow: newWindow)
        print("7. 即将添加到窗口 - willMove(toWindow:)")
    }

    // 8. 已添加到窗口
    override func didMoveToWindow() {
        super.didMoveToWindow()
        print("8. 已添加到窗口 - didMoveToWindow")
        // 只有添加到window后,View才会真正显示在屏幕上
    }

    // 9. 销毁(deinit)
    deinit {
        print("9. View销毁 - deinit")
        // 释放View相关资源(如移除子视图、取消动画)
    }
}

关键说明

  • layoutSubviews:最常用的方法,每次 View 的尺寸变化都会触发,适合手动调整子视图布局(若使用 AutoLayout,系统会自动处理,无需重写)。
  • draw(_:) :仅在需要手动绘制内容时重写,避免在其中做耗时操作(会影响渲染性能);调用setNeedsDisplay()可触发重新绘制。
  • Window 关联:View 只有添加到UIWindow(应用的主窗口)后,才会被渲染并显示在屏幕上;didMoveToWindow是 View 真正 “可见” 的标志。
  • 销毁:当 View 从父视图移除且无强引用时,deinit触发,需确保子视图也被正确释放。

总结

  1. 应用生命周期:全局层面,管理 App 从启动到终止的状态,核心是UIApplicationDelegate的代理方法,关注前台 / 后台切换和资源保存。
  2. 视图控制器生命周期:页面层面,核心是viewDidLoad(一次性初始化)、viewWillAppear(每次显示刷新)、deinit(资源释放),是业务逻辑的主要载体。
  3. 视图生命周期:控件层面,依附于 VC,核心是layoutSubviews(布局)和draw(_:)(绘制),关注控件尺寸调整和视觉渲染。

三者的关联:App 启动后创建根 VC → VC 创建并加载 View → View 添加到 Window 显示 → App 进入前台活跃状态;App 进入后台时,VC 的 View 会被隐藏,资源可按需释放。

Swift 6.2 列传(第十六篇):阿朱的“易容术”与阿紫的“毒药测试”

在这里插入图片描述

摘要:在 Swift 6.2 的并发江湖中,我们迎来了两项截然不同的新功能:一项是关于极度精妙的文本侦查术(SE-0448 正则表达式向后查找断言),另一项则是关于面对应用崩溃时的从容不迫(ST-0008 退出测试)。大熊猫侯佩将与阿朱、阿紫这对姐妹花,共同演绎这冰火两重天的技术奥秘。

0️⃣ 🐼 序章:雁门关前的技术难题

雁门关,数据流与现实交错的虚拟战场。

大熊猫侯佩正对着一块全息屏幕发呆,屏幕上是无数条交易记录,他正努力寻找他藏匿的竹笋基金。他用手摸了摸自己的头顶,确定了头绝对没有秃之后,才稍微心安。

他身旁站着一位温柔婉约的绿衣女子,正是阿朱。阿朱以易容术闻名江湖,擅长在纷乱的文本中寻找和伪装信息,她的心愿是天下太平,性格宽厚善良。

在这里插入图片描述

“侯大哥,”阿朱指着一堆交易记录说,“我想找到所有以 金币符号 $ 结算的价格,但我只想匹配出后面的数字,而不要把那个 $符号也匹配进去。我要用这些数字去结算账单,符号留着下次易容用。”

在本次大模型中,您将学到如下内容:

  • 0️⃣ 🐼 序章:雁门关前的技术难题
  • 1️⃣ 🔎 阿朱的易容术:Regex lookbehind assertions
  • 2️⃣ 🧪 阿紫的毒药测试:Exit Tests 的“置之死地” (ST-0008)
    • #expect(processExitsWith:) 的安全结界
  • 3️⃣ 🎁 尾声:崩溃现场的“遗物”与下一章的伏笔

侯佩为难地挠了挠头:“以前的 Regex(正则表达式),要么就全部匹配进去,要么就得用复杂的捕获组再分离。要想实现‘只看前因,不取前因’,简直难如登天啊!”

在这里插入图片描述


1️⃣ 🔎 阿朱的易容术:Regex lookbehind assertions

阿朱的问题,正是 SE-0448 所要解决的:向后查找断言(lookbehind assertions)

传统的正则表达式,可以轻松地实现“向前看”(Lookahead),例如 A(?=B),匹配 A,但前提是 A 后面跟着 B。

在这里插入图片描述

而现在,Swift 6.2 赋予了我们 “向后看” 的能力,即 (?<=A)B:匹配 B,但前提是 B 前面紧跟着 A。最关键的是,A(前置条件)不会被纳入最终的匹配结果中。

侯佩拿起代码卷轴,为阿朱演示了这招“庖丁解牛”般的绝技:

let string = "Buying a jacket costs $100, and buying shoes costs $59.99."

// (?<=\$): 向后查找断言,确认当前位置前面紧跟着一个 $ 符号。
// \d+     : 匹配至少一个数字(价格的整数部分)。
// (?:\.\d{2})?: 匹配可选的小数点和小数部分(?: 是非捕获组)。
let regex = /(?<=\$)\d+(?:\.\d{2})?/ 

for match in string.matches(of: regex) {
    // 最终输出的 match.output 只有数字,不包含 $ 符号
    print(match.output) 
}

// 输出:
// 100
// 59.99

“看到了吗,阿朱姑娘?”侯佩得意洋洋,“这个 (?<=$) 就是你的易容术精髓。它帮你确认了身份(前面必须是金币),但在匹配结果中,它却完美地把自己隐藏了起来,片叶不沾身!

在这里插入图片描述

阿朱喜出望外:“太妙了!这样我就可以精准地提取数据,再也不用担心多余的符号来捣乱了!”

2️⃣ 🧪 阿紫的毒药测试:Exit Tests 的“置之死地” (ST-0008)

就在侯佩和阿朱沉浸在正则表达式的精妙中时,一阵刺鼻的硫磺味突然袭来!

另一位身着紫衣的少女,阿紫,从烟雾中走了出来。阿紫的特点是心狠手辣,喜欢用毒,而且热衷于测试“极限”

在这里插入图片描述

“姐姐,你在玩这么幼稚的游戏?”阿紫轻蔑一笑,“我的任务才刺激。我要测试我最新的**‘鹤顶红’代码**,确保它能让整个应用彻底崩溃并退出!”

侯佩吓得连退三步:“你要测试崩溃?阿紫姑娘,你知道这意味着什么吗?应用崩溃,测试系统也会跟着崩溃啊!这叫一锅端!”

在这里插入图片描述

阿紫的测试目标,正是那些会触发 precondition()fatalError() 导致进程退出的代码。

struct Dice {
    // 掷骰子功能
    func roll(sides: Int) -> Int {
        // 🚨 前提条件:骰子面数必须大于零!
        // 如果 sides <= 0,程序将立即崩溃退出!
        precondition(sides > 0) 
        return Int.random(in: 1...sides)
    }
}

“以前,我们要么不能测,要么就得用各种奇技淫巧来捕获这种‘致命错误’。”侯佩擦着汗说,“但现在 Swift Testing 带来了 ST-0008:Exit Tests,让我们能优雅地‘置之死地而后生’!”

在这里插入图片描述

#expect(processExitsWith:) 的安全结界

Swift 6.2 引入了 #expect(processExitsWith:),它就像是一个安全结界,允许我们在隔离的子进程中执行可能导致崩溃的代码,然后捕获并验证这个退出行为。

@Test func invalidDiceRollsFail() async throws {
    let dice = Dice()

    // 🛡️ 关键:使用 #expect 包裹,并等待结果
    await #expect(processExitsWith: .failure) {
        // 在这里,roll(sides: 0) 会导致隔离的子进程崩溃退出
        let _ = dice.roll(sides: 0)
    }
    
    // 如果子进程如期以 .failure 状态退出,则测试通过。
    // 如果它没有崩溃,或者崩溃状态不对,则测试失败。
}

🔍 异步执行的关键:await 注意,这里必须使用 await。这是因为在幕后,测试框架必须启动一个专用的、独立的进程来执行危险代码。它会暂停当前测试,直到子进程运行完毕并返回退出状态。这才是真正的隔离测试

在这里插入图片描述

阿紫满意地拍了拍手:“现在我的毒药(代码)终于可以在实验室(测试环境)里安全地爆炸了!我不仅可以测试它会死(failure),还可以测试它死得很安详(success)或其他退出状态。”

3️⃣ 🎁 尾声:崩溃现场的“遗物”与下一章的伏笔

侯佩摸了摸自己的头发,确认没有被阿紫的毒气熏掉,然后问道:“阿紫姑娘,你这个毒药测试虽然厉害,但是你有没有想过一个问题?”

在这里插入图片描述

“什么问题?”阿紫挑了挑眉。

“如果这个 roll(sides: 0) 崩溃了,但它在崩溃前,生成了一个关键的调试日志文件,或者一个记录了现场数据的**‘遗物’**,你能不能把这个遗物附着到测试报告里?”

阿紫一愣:“不能。测试报告里只显示了‘崩溃了’这个结果,但我不知道崩溃前骰子(程序)到底在想什么!我需要那个遗物来分析我的毒药配方!”

在这里插入图片描述

阿朱也附和道:“是啊,侯大哥。就像我易容时,如果失败了,我希望在失败的记录旁边,能附上一张当时的照片,这样下次就知道是哪个环节出了错。”

侯佩微微一笑,从怀里掏出了一张写着 ST-0009 的秘籍:“两位姑娘,不必烦恼。下一章,Swift Testing 就能帮你们把这些日志、数据和现场文件,像附着‘随身物品’一样,直接捆绑到失败的测试报告上。这招就叫……”

在这里插入图片描述

(欲知后事如何,且看下回分解:Swift Testing: Attachments —— 如何将崩溃现场的证据(日志、截图、数据文件)直接附着到测试报告上,让 Bug 无所遁形。)

拒绝“假死”:为何上滑关闭是测试大忌?揭秘 iOS 真实 OOM 触发指南

在这里插入图片描述

☔️ 引子

在赛博都市“新硅谷”(Neo-Silicon Valley)的第 1024 层地下室里,资深 iOS 赏金猎人——老李(Old Li),正盯着全息屏幕上一行行红色的报错代码发愁。他嘴里叼着一根早已熄灭的合成电子烟,眉头皱得能夹死一只纳米苍蝇。

旁边漂浮着的 AI 助手“小白”发出了机械的合成音:“警报,内存溢出测试失败。目标 App 依然像个赖皮一样活着。”

在这里插入图片描述

老李叹了口气:“这年头的 App,一个个都练成了‘金刚不坏之身’。我想测一下后台上传功能在**低内存(Low RAM)**情况下的表现,结果这破手机内存大得像海一样,怎么都填不满。”

“老板,直接在 App Switcher(多任务切换器)里把它划掉不就行了?”小白天真地问道。

**在本篇博文中,您将学到如下内容: **

  • ☔️ 引子
  • 🕵️‍♂️ 第一章:真死还是假死?这是一个问题
  • 🔮 第二章:失传的“清内存大法”
  • 🛠️ 步骤一:召唤“假肢”(Assistive Touch)
  • 🧨 步骤二:准备“关机仪式”
  • 🩸 步骤三:致命一击(The Purge)
  • 🧟‍♂️ 第三章:为什么我们需要这种“假死”?
  • ⚖️ 第四章:技术验尸——“被杀”与“自杀”的区别
  • 🎬 终章:深藏功与名

老李冷笑一声,敲了一下小白的金属外壳:“图样图森破!手滑杀掉那是‘斩立决’,系统因内存不足杀掉那是‘自然死亡’。对于后台任务来说,这区别可大了去了。要想骗过死神,我们得用点‘阴招’。”

老李从积灰的档案袋里掏出一份绝密文档——《iOS 内存清空指南》。

在这里插入图片描述


🕵️‍♂️ 第一章:真死还是假死?这是一个问题

最近老李接了个大活儿,要为一个 App 开发 Background Uploading(后台上传)功能。这活儿最棘手的地方在于:你得确保当系统因为 RAM constraints(内存限制)或其他不可抗力把你的 App 挂起甚至杀掉时,这上传任务还得能像“借尸还魂”一样继续跑。

要想测试这个场景,最直接的办法就是清空设备的 RAM memory。但这可不像在电脑上拔掉电源那么简单。

小白不解:“不就是上划杀进程吗?”

在这里插入图片描述

“错!”老李严肃地解释道,“打开 Task Switcher 然后强行关闭 App,这在系统眼里属于‘用户主动终止’。这就像是不仅杀了人,还顺手把复活点给拆了。而我们需要的是模拟 App 被系统‘挤’出内存,这才是真正的Forced out of memory。”

简而言之,我们需要制造一场完美的“意外”,让 App 以为自己只是因为太胖被系统踢了出去,而不是被用户嫌弃。


🔮 第二章:失传的“清内存大法”

幸运的是,在 iOS 的底层代码深处,藏着一个不为人知的“秘技”。这招能像灭霸打响指一样,瞬间清空 iOS 设备的 RAM memory,让你的 App 享受到和真实内存不足时一样的“暴毙”待遇。

老李按灭了烟头,开始向小白传授这套“还我漂漂拳”:

在这里插入图片描述

🛠️ 步骤一:召唤“假肢”(Assistive Touch)

如果你的测试机是全面屏(没有 Home 键),你得先搞个虚拟的。 “去 Settings → Accessibility → Touch → Enable Assistive Touch。”老李指挥道。

在这里插入图片描述

屏幕上瞬间浮现出一个半透明的小圆球。 “这就是通往内存地狱的钥匙。”

技术批注: 对于有实体 Home 键的老古董设备,这一步可以跳过。

🧨 步骤二:准备“关机仪式”

在这里插入图片描述

这一步需要一点手速,就像是在玩格斗游戏搓大招。 “听好了:Volume Up(音量加),Volume Down(音量减),然后死死按住 Power Button(电源键)!”

在这里插入图片描述

老李的手指在机身上飞舞,直到屏幕上出现了那个熟悉的“滑动来关机”界面。

🩸 步骤三:致命一击(The Purge)

“就是现在!”老李大喝一声。

在关机界面出现后,千万别滑那个关机条。点击刚才召唤出来的 Assistive Touch 小圆球,找到里面的 Home Button(主屏幕按钮),然后——长按它

在这里插入图片描述

一直按着,直到屏幕一闪,或者突然跳回输入密码的界面。

“恭喜你,”老李擦了擦额头的汗,“你刚刚成功把这台设备的 RAM memory 洗劫一空。现在,后台那些苟延残喘的 App 已经被系统无情地踢出了内存。”

在这里插入图片描述


🧟‍♂️ 第三章:为什么我们需要这种“假死”?

小白看着屏幕上被清理得干干净净的后台,数据流终于开始正常波动了。

“这就好比演习,”老李解释道,“当我们在开发那些依赖于 Background Resuming(后台恢复)的功能时——比如后台上传、下载,或者定位服务——模拟 Out of Memory 场景简直是救命稻草。”

在这里插入图片描述

最让老李爽的一点是,这个操作完全脱离了 Xcode。 “以前还要连着线看 Debugger,现在我可以把手机扔给隔壁 QA 部门那个只会吃薯片的测试员,告诉他:‘按这个秘籍操作,如果上传断了,就是你们的问题,如果没断,就是我的功劳。’”


⚖️ 第四章:技术验尸——“被杀”与“自杀”的区别

为了防止小白以后出去乱说,老李决定再深入科普一下其中的Hardcore原理。

在这里插入图片描述

一个被 Forced out of RAM 的 App,在用户眼里并没有完全死透。它依然会出现在 App Switcher 里,就像个植物人。更重要的是,任何已经注册的 Background Processes(后台进程,比如 NSURLSession 的后台任务)依然在系统的监管下继续运行。

  • 正常死亡(Low Memory): 当用户开了个吃内存的大游戏,或者你的 App 很久没用了,系统为了腾地儿,会把你的 App 从内存里踢出去。当用户再次点击图标时,App 会经历一次 Fresh Launch(冷启动),但系统会给机会让它处理之前没干完的后台活儿。
  • 非正常死亡(Force Close): 当你在多任务界面上滑杀掉 App 时,iOS 会判定:“这刁民不想让这个 App 活了。”于是,系统会大义灭亲,禁止该 App 继续在后台搞小动作。所有的上传、下载任务会被立即 Cancelled(取消)。

在这里插入图片描述

所以,只有用老李刚才那招“清内存大法”,才能真实模拟用户在刷抖音、玩原神导致内存不足时,你的 App 在后台是否还能坚强地把文件传完。


🎬 终章:深藏功与名

测试通过,全息屏幕上显示出了令人安心的绿色 SUCCESS 字样。

在这里插入图片描述

老李站起身,伸了个懒腰,骨头发出噼里啪啦的响声。“行了,小白,打包发布。今晚不用加班修 Bug 了。”

他看了一眼窗外新硅谷那绚烂而又冰冷的霓虹灯。在这个充满 Bug 和 Patch 的世界里,有时候,你必须学会如何正确地“杀死”你的 App,才能让它更好地活下去。

在这里插入图片描述

“记住,”老李走出门口前回头对小白说,“杀进程不是目的,目的是为了验证它有没有重生的勇气。

大门缓缓关闭,只留下那个悬浮的 Assistive Touch 按钮,在黑暗中微微闪烁,仿佛一只窥探内存深处的眼睛。

在这里插入图片描述

SSE Connect 数据解析详解

前言

SSE(Server-Sent Events) 是一种基于 HTTP 的服务器单向推送技术。相比 WebSocket 的双向通信,SSE 更轻量、实现更简单,非常适合服务器向客户端持续推送数据的场景。ChatGPT、Claude 等 AI 产品都使用 SSE 来实现流式输出。

本文以 iOS 客户端实现为例,详细讲解 SSE 数据的接收与解析过程。


一、完整示例:一个 SSE 事件从发送到接收的全过程

服务器发送的数据

event: chunk
id: 1
data: {"content":"Hello"}

⚠️ 注意:最后有一个空行,这是事件结束的标志!


第一步:服务器发送,网络传输

服务器发送的原始字节流:

e v e n t :   c h u n k \n i d :   1 \n d a t a :   { . . . } \n \n

问题:网络传输时,数据可能被分成多个块到达客户端。

假设网络把数据分成了 3 块:

数据块 内容
块 1 "event: chu"
块 2 "nk\nid: 1\nda"
块 3 "ta: {\"content\":\"Hello\"}\n\n"

第二步:行解析器处理(OKGrowthUTF8LineParser)

2.1 收到块 1:"event: chu"

┌────────────────────────────────────────────────────────────┐
│ 输入: "event: chu"                                         │
│                                                            │
│ 处理过程:                                                   │
│   1. 缓冲区当前为空: ""                                     │
│   2. 合并: "" + "event: chu" = "event: chu"                │
│   3. 扫描换行符: 没找到 \n                                  │
│   4. 没有完整行,全部存入缓冲区                              │
│                                                            │
│ 缓冲区: "event: chu"                                       │
│ 输出: []  ← 空数组,没有完整行                              │
└────────────────────────────────────────────────────────────┘

2.2 收到块 2:"nk\nid: 1\nda"

┌────────────────────────────────────────────────────────────┐
 输入: "nk\nid: 1\nda"                                      
                                                            
 处理过程:                                                   
   1. 缓冲区当前: "event: chu"                               
   2. 合并: "event: chu" + "nk\nid: 1\nda"                  
         = "event: chunk\nid: 1\nda"                        
   3. 扫描换行符:                                            
      - 位置 12 找到 \n  提取 "event: chunk"               
      - 位置 18 找到 \n  提取 "id: 1"                      
      - "da" 后面没有 \n,存入缓冲区                         
                                                            
 缓冲区: "da"                                               
 输出: ["event: chunk", "id: 1"]                            
└────────────────────────────────────────────────────────────┘

2.3 收到块 3:"ta: {\"content\":\"Hello\"}\n\n"

┌────────────────────────────────────────────────────────────┐
 输入: "ta: {\"content\":\"Hello\"}\n\n"                    
                                                            
 处理过程:                                                   
   1. 缓冲区当前: "da"                                       
   2. 合并: "da" + "ta: {...}\n\n"                          
         = "data: {\"content\":\"Hello\"}\n\n"              
   3. 扫描换行符:                                            
      - 位置 27 找到 \n  提取 "data: {...}"                
      - 位置 28 找到 \n  提取 ""   空行!                  
                                                            
 缓冲区: ""   清空                                         
 输出: ["data: {\"content\":\"Hello\"}", ""]                
└────────────────────────────────────────────────────────────┘

2.4 行解析器总结

经过 3 次数据块处理,行解析器依次输出:

次序 输出的完整行
块 1 后 [] (无)
块 2 后 ["event: chunk", "id: 1"]
块 3 后 ["data: {...}", ""]

合计得到 4 行: "event: chunk", "id: 1", "data: {...}", ""


第三步:事件解析器处理(OKGrowthEventParser)

SSEClient 将行解析器输出的每一行,依次传给事件解析器。

3.1 解析第 1 行:"event: chunk"

┌────────────────────────────────────────────────────────────┐
│ 输入: "event: chunk"                                       │
│                                                            │
│ 处理过程:                                                   │
│   1. 行长度 > 0,不是空行                                   │
│   2. 查找冒号位置: 5                                        │
│   3. 字段名 = "event"                                      │
│   4. 字段值 = "chunk" (冒号后面,跳过空格)                   │
│   5. 字段名是 "event",存储 eventType                       │
│                                                            │
│ 当前状态:                                                   │
│   eventType = "chunk"  ✓                                   │
│   eventId   = ""                                           │
│   data      = ""                                           │
│                                                            │
│ 动作: 继续等待下一行                                        │
└────────────────────────────────────────────────────────────┘

3.2 解析第 2 行:"id: 1"

┌────────────────────────────────────────────────────────────┐
│ 输入: "id: 1"                                              │
│                                                            │
│ 处理过程:                                                   │
│   1. 行长度 > 0,不是空行                                   │
│   2. 查找冒号位置: 2                                        │
│   3. 字段名 = "id"                                         │
│   4. 字段值 = "1"                                          │
│   5. 字段名是 "id",存储 eventId                            │
│                                                            │
│ 当前状态:                                                   │
│   eventType = "chunk"  ✓                                   │
│   eventId   = "1"      ✓                                   │
│   data      = ""                                           │
│                                                            │
│ 动作: 继续等待下一行                                        │
└────────────────────────────────────────────────────────────┘

3.3 解析第 3 行:"data: {\"content\":\"Hello\"}"

┌────────────────────────────────────────────────────────────┐
 输入: "data: {\"content\":\"Hello\"}"                      
                                                            
 处理过程:                                                   
   1. 行长度 > 0,不是空行                                   
   2. 查找冒号位置: 4                                        
   3. 字段名 = "data"                                       
   4. 字段值 = "{\"content\":\"Hello\"}"                    
   5. 字段名是 "data",追加到 data                           
      (当前 data 为空,直接赋值)                              
                                                            
 当前状态:                                                   
   eventType = "chunk"                                     
   eventId   = "1"                                         
   data      = "{\"content\":\"Hello\"}"                   
                                                            
 动作: 继续等待下一行                                        
└────────────────────────────────────────────────────────────┘

3.4 解析第 4 行:"" (空行) ⚡

┌────────────────────────────────────────────────────────────┐
│ 输入: ""  (空行)                                           │
│                                                            │
│ 处理过程:                                                   │
│   1. 行长度 == 0,是空行!                                  │
│   2. ⚡ 空行触发事件分发!                                   │
│                                                            │
│ 当前状态 (即将分发):                                        │
│   eventType = "chunk"                                      │
│   eventId   = "1"                                          │
│   data      = "{\"content\":\"Hello\"}"                    │
│                                                            │
│ 执行 dispatchEvent():                                      │
│   1. 调用回调: onEvent("chunk", "1", "{...}")              │
│   2. 重置状态:                                              │
│      eventType = ""                                        │
│      eventId   = ""                                        │
│      data      = ""                                        │
│                                                            │
│ 动作: 🎯 触发回调!准备解析下一个事件                        │
└────────────────────────────────────────────────────────────┘

第四步:事件分发,回调业务层

┌────────────────────────────────────────────────────────────┐
│                      回调链                                 │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  EventParser.dispatchEvent()                               │
│       │                                                    │
│       │  onEvent("chunk", "1", "{\"content\":\"Hello\"}")  │
│       ↓                                                    │
│  SSEClient.handleEvent()                                   │
│       │                                                    │
│       │  判断: eventType != "connected",不更新状态         │
│       │                                                    │
│       │  onTextChunk("chunk", "1", "{...}")                │
│       ↓                                                    │
│  MLNSSETool                                                │
│       │                                                    │
│       │  [onTextChunk addStringArgument:@"chunk"];         │
│       │  [onTextChunk addStringArgument:@"1"];             │
│       │  [onTextChunk addStringArgument:@"{...}"];         │
│       │  [onTextChunk callIfCan];                          │
│       ↓                                                    │
│  Lua 业务层                                                │
│       │                                                    │
│       │  onEvent("chunk", "1", '{"content":"Hello"}')      │
│       ↓                                                    │
│  业务代码处理                                               │
│       │                                                    │
│       │  local json = cjson.decode(data)                   │
│       │  print(json.content)  -- 输出: Hello               │
│       │  更新 UI 显示                                       │
│       ↓                                                    │
│  ✅ 完成!                                                  │
│                                                            │
└────────────────────────────────────────────────────────────┘

完整流程图(从服务器到 Lua)

服务器发送: "event: chunk\nid: 1\ndata: {...}\n\n"
                          
                           网络分块传输
┌─────────────────────────────────────────────────────────────┐
                     第一步:网络层                            
├─────────────────────────────────────────────────────────────┤
1: "event: chu"                                          
2: "nk\nid: 1\nda"                                       
3: "ta: {...}\n\n"                                       
└─────────────────────────────────────────────────────────────┘
                          
                           NSURLSession.didReceiveData
┌─────────────────────────────────────────────────────────────┐
                 第二步:行解析器                               
                 (UTF8LineParser)                            
├─────────────────────────────────────────────────────────────┤
1  []                                                   
2  ["event: chunk", "id: 1"]                            
3  ["data: {...}", ""]                                  
                                                             
  合计得到4行: `"event: chunk"`, `"id: 1"`, `"data: {...}"`, `""`  
└─────────────────────────────────────────────────────────────┘
                          
                           逐行传递
┌─────────────────────────────────────────────────────────────┐
                 第三步:事件解析器                             
                 (EventParser)                               
├─────────────────────────────────────────────────────────────┤
1"event: chunk"   eventType = "chunk"                 
2"id: 1"          eventId = "1"                       
3"data: {...}"    data = "{...}"                      
4""                触发 dispatchEvent()              
└─────────────────────────────────────────────────────────────┘
                          
                           onEvent 回调
┌─────────────────────────────────────────────────────────────┐
                     第四步:事件分发                           
├─────────────────────────────────────────────────────────────┤
  SSEClient.handleEvent("chunk", "1", "{...}")               
                                                            
  MLNSSETool.onTextChunk("chunk", "1", "{...}")              
                                                            
  Lua: onEvent("chunk", "1", '{"content":"Hello"}')          
                                                            
      业务代码: 解析 JSON,更新 UI                              
└─────────────────────────────────────────────────────────────┘
                          
                          
                     处理完成!


二、关键点总结

2.1 为什么需要行解析器?

网络数据分块到达,一行可能被拆成多块。行解析器用缓冲区解决这个问题。

2.2 为什么空行这么重要?

event: chunk     ← 存储 eventType,不触发
id: 1            ← 存储 eventId,不触发
data: {...}      ← 存储 data,不触发
                 ← ⚡ 只有空行才触发事件分发!

空行 = 事件结束的信号

2.3 一个事件的完整生命周期

阶段 输入 输出
网络传输 字节流 数据块
行解析器 数据块 文本行数组
事件解析器 文本行 event/id/data
空行触发 "" dispatchEvent()
回调链 event/id/data Lua onEvent
❌