``` ### 3. 滚动跳转核心逻辑 ```typescript const scrollToQuestion = (questionId: string) => { // 1. 检查是否已完成 if (answeredQuestionMap.value.has(questionId)) return // 2. 查找对应DOM元素 const formElement = document.querySelector(`[data-question-id="${questionId}"]`) // 3. 执行滚动和聚焦 if (formElement) { formElement.scrollIntoView({ behavior: 'smooth', block: 'center' }) // 自动聚焦输入框 const inputElement = formElement.querySelector('input, textarea, select') inputElement?.focus() } } ``` ## 💻 完整实现代码 ### 1. 主组件 (FormPanel.vue) ```vue ``` ### 2. 动态表单组件 (DynamicForm.vue) ```vue ``` ### 3. 使用示例 (App.vue) ```vue ``` ## 🎨 样式优化建议 ### 1. 进度条样式增强 ```css .progress-segment { position: relative; overflow: hidden; } .progress-segment::after { content: ''; position: absolute; top: 0; left: -100%; width: 100%; height: 100%; background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.4), transparent); transition: left 0.5s; } .segment-pending:hover::after { left: 100%; } ``` ### 2. 高亮动画效果 ```css @keyframes highlight { 0% { background-color: transparent; } 50% { background-color: rgba(59, 130, 246, 0.2); } 100% { background-color: transparent; } } .form-item-highlight { animation: highlight 2s ease-in-out; } ``` ## 🚀 进阶功能 ### 1. 添加进度百分比显示 ```vue ``` ### 2. 添加键盘导航支持 ```typescript // 添加键盘事件监听 onMounted(() => { document.addEventListener('keydown', handleKeydown) }) onUnmounted(() => { document.removeEventListener('keydown', handleKeydown) }) const handleKeydown = (event: KeyboardEvent) => { if (event.key === 'Tab' && event.shiftKey) { // Shift + Tab: 跳转到上一个未完成项目 jumpToPreviousUncompleted() } else if (event.key === 'Tab') { // Tab: 跳转到下一个未完成项目 jumpToNextUncompleted() } } ``` ### 3. 添加保存草稿功能 ```typescript const saveDraft = () => { localStorage.setItem('form-draft', JSON.stringify(formData.value)) } const loadDraft = () => { const draft = localStorage.getItem('form-draft') if (draft) { Object.assign(formData.value, JSON.parse(draft)) } } ``` ## 📱 移动端适配 ```css @media (max-width: 768px) { .progress-segment { min-width: 20px; } .form-content { padding: 1rem; } .panel-header { padding: 1rem; } } ``` ## 🧪 测试建议 ### 1. 单元测试 ```typescript import { mount } from '@vue/test-utils' import FormPanel from '@/components/FormPanel.vue' describe('FormPanel', () => { it('should scroll to question when clicked', async () => { const wrapper = mount(FormPanel, { props: { fields: [ { name: 'test1', label: 'Test 1', type: 'text' }, { name: 'test2', label: 'Test 2', type: 'text' }, ], }, }) // 模拟点击进度条 const progressSegment = wrapper.find('.segment-pending') await progressSegment.trigger('click') // 验证滚动行为 expect(document.querySelector).toHaveBeenCalledWith('[data-question-id="test1"]') }) }) ``` ### 2. E2E 测试 ```typescript // Cypress 测试示例 describe('Progress Bar Navigation', () => { it('should navigate to form fields when clicking progress segments', () => { cy.visit('/form') // 点击第一个未完成项目 cy.get('.segment-pending').first().click() // 验证页面滚动到对应位置 cy.get('[data-question-id]').should('be.visible') // 验证输入框获得焦点 cy.focused().should('have.attr', 'type', 'text') }) }) ``` ## 🎯 最佳实践 1. **性能优化**: 使用 `debounce` 防抖处理频繁的表单数据变化 2. **可访问性**: 添加 `aria-label` 和键盘导航支持 3. **错误处理**: 添加滚动失败的回退机制 4. **用户体验**: 提供加载状态和错误提示 5. **代码维护**: 将滚动逻辑抽取为独立的 composable ## 📚 总结 这个进度条点击跳转功能通过以下几个核心概念实现： 1. **数据驱动**: 使用响应式数据管理进度状态 2. **DOM 操作**: 通过 `data-*` 属性定位表单元素 3. **平滑动画**: 利用 `scrollIntoView` API 实现平滑滚动 4. **用户反馈**: 通过视觉高亮和自动聚焦提升体验 这种实现方式不仅提供了良好的用户体验，还保持了代码的可维护性和扩展性。您可以根据具体需求对功能进行定制和扩展。 ## 🔗 相关资源 - [Vue 3 官方文档](https://vuejs.org/) - [Ant Design Vue 组件库](https://antdv.com/) - [Tailwind CSS 样式框架](https://tailwindcss.com/) - [MDN scrollIntoView API](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) ]]> http://herong.info/posts/requirement-realization-1 http://herong.info/posts/requirement-realization-1 Fri, 05 Sep 2025 00:54:31 GMT ** 与 **X-Device-Id（设备唯一码）** 请求 `/passkeys/register/options`。 - 浏览器完成 `navigator.credentials.create(...)` 后，将结果 + `deviceIdentifier` 回传 `/passkeys/register/verify`。 - 后端：从 **token 解析 userId**，生成/校验 challenge、**入库凭证**，并执行**设备唯一绑定**（`deviceId -> userId`）。 > 关键点：**不要尝试枚举本地是否已有凭证**；隐私模型不允许。登录态下的“绑定”其实就是“已知用户的注册流程”。 --- ## 设计要点 - **用户唯一标识**：后端**不靠前端传 userId**，而是从 **JWT** 中解析（`sub`）→ 更安全。 - **设备唯一**：前端生成/缓存 `deviceId`，通过 `X-Device-Id` 头传给后端；后端使用 `dvc:owner:${deviceId}` 在 Redis 做“一致性绑定”。 - **防重复注册**：注册 options 中使用 `excludeCredentials`（由后端查询该用户已绑定的 credentialId）。 - **风控与速率限制**：对 `deviceId` 做限流（如 1h/3 次），并在 verify 阶段二次校验。 - **协议对齐**：保持与登录/JIT 注册完全相同的编码规范（字节字段统一 **base64url**）。 --- ## 前端实现（Web） > 仅新增**一个按钮事件**用于“绑定通行密钥”。代码自包含；把 `BASE_URL` 改成你的后端地址即可。 > 复杂逻辑均在上一行写注释。 ```html 绑定通行密钥

``` > 若你在 **uni-app**（H5）里使用，也可沿用同样逻辑；在 **App（UTS 插件）** 上只需把 `navigator.credentials.create` 替换为你的 `passkeys.createPasskey(optionsJson)` 即可，其余协议不变。 --- ## 后端实现（NestJS，仅给“增量/改动片段”） > 你的工程里已有 JIT 与登录接口。这里**新增/完善**“**已登录的注册（绑定）**”两个端点，并对 Service 增强**按 token 解析 user** 与**设备唯一**。 ### 1）Controller 片段 ```ts // 复杂：新增“已登录绑定”端点；依赖 JWT 守卫把 user 注入 request.user import { Controller, Post, Req, UseGuards, Body } from "@nestjs/common"; import { AuthGuard } from "@nestjs/passport"; import { PasskeysService } from "../../services/passkeys.service"; @Controller("passkeys") export class PasskeysController { constructor(private readonly passkeysService: PasskeysService) {} // 复杂：注册（绑定）options——登录态 @UseGuards(AuthGuard("jwt")) @Post("register/options") getBindOptions(@Req() req: any) { // 复杂：设备ID从 Header/Cookie/IP 提取，用于风控与后续绑定一致性 const deviceIdentifier = req.headers["x-device-id"] || req.cookies?.dvc || `ip:${req.ip}`; const userId = req.user?.sub; // 复杂：从 JWT 解析出的 userId return this.passkeysService.issueRegistrationOptionsForUser( userId, deviceIdentifier ); } // 复杂：注册（绑定）verify——登录态 @UseGuards(AuthGuard("jwt")) @Post("register/verify") verifyBind(@Req() req: any, @Body() body: any) { const deviceIdentifier = req.headers["x-device-id"] || body.deviceIdentifier || req.cookies?.dvc || `ip:${req.ip}`; const userId = req.user?.sub; return this.passkeysService.verifyRegistrationForUser( userId, body, deviceIdentifier ); } } ``` ### 2）Service 片段 ```ts // 复杂：为“已登录绑定”增加两个方法 @Injectable() export class PasskeysService { // ... 省略已有依赖与构造 // 复杂：签发已登录用户的注册 options（含 excludeCredentials 与限流） async issueRegistrationOptionsForUser( userId: string, deviceIdentifier?: string ) { if (!userId) throw new UnauthorizedException("未登录"); // 复杂：限流（1h/3次） if (deviceIdentifier) { const rlKey = `rl:bind:${deviceIdentifier}`; const n = await this.redisService.incrementKey(rlKey); if (n === 1) await this.redisService.expireKey(rlKey, 3600); if (n > 3) throw new BadRequestException("操作过于频繁，请稍后再试"); } const rpId = this.configService.get("RP_ID"); // 复杂：查询该用户已有凭证，构造 excludeCredentials 防重复注册 const existing = await this.staffService.findManyCredentialsByUserId( userId ); // 需要你实现查询 const exclude = (existing || []).map((c: any) => ({ id: Buffer.from(c.credentialId, "base64url"), type: "public-key" as const, })); const options = await generateRegistrationOptions({ rpName: "Your App", rpID: rpId, // 复杂：v11+ 要求 userID 为字节；这里直接用 UTF-8 Buffer userID: Buffer.from(String(userId), "utf8"), userName: String(userId), attestationType: "none", // 复杂：兼容性更好（ES256 + RS256） supportedAlgorithmIDs: [-7, -257], authenticatorSelection: { residentKey: "required", // 复杂：要求可发现凭证，便于后续一键直登 userVerification: "preferred", }, excludeCredentials: exclude, extensions: { credProps: true }, }); // 复杂：将 challenge(base64url) 与 user 绑定，TTL 5 分钟 const ch = typeof options.challenge === "string" ? options.challenge : Buffer.from(options.challenge).toString("base64url"); await this.redisService.setWithTimeToLive( `webauthn:register:${userId}`, ch, 300 ); return { options }; } // 复杂：校验 attestation + 入库 + 设备唯一绑定（不重新发 token，也可选择刷新） async verifyRegistrationForUser( userId: string, requestBody: any, deviceIdentifier?: string ) { if (!userId) throw new UnauthorizedException("未登录"); const rpId = this.configService.get("RP_ID"); const origin = this.configService.get("ORIGIN"); const cachedChallenge = await this.redisService.getValue( `webauthn:register:${userId}` ); if (!cachedChallenge) throw new BadRequestException("注册挑战不存在或已过期"); const verification = await verifyRegistrationResponse({ response: requestBody, expectedRPID: rpId, expectedOrigin: origin, expectedChallenge: cachedChallenge, requireUserVerification: true, // 复杂：绑定建议要求 UV }); if (!verification.verified || !verification.registrationInfo) { throw new UnauthorizedException("注册校验失败"); } const { credential } = verification.registrationInfo; const credentialIdB64url = Buffer.from(credential.id).toString("base64url"); const publicKey = Buffer.from(credential.publicKey); // 存二进制或 base64 皆可 const counter = credential.counter ?? 0; // 复杂：入库（若同 credentialId 已存在且属同人，可忽略/幂等） await this.staffService.upsertCredential({ userId, credentialId: credentialIdB64url, publicKey, counter, transports: credential.transports ? JSON.stringify(credential.transports) : null, }); // 复杂：设备唯一绑定（若存在 deviceId 且已被他人占用，则拒绝） if (deviceIdentifier) { const key = `dvc:owner:${deviceIdentifier}`; const existed = await this.redisService.getValue(key); if (existed && existed !== String(userId)) { throw new ForbiddenException("此设备已绑定其他账号"); } // 绑定一年（或不设 TTL） await this.redisService.setWithTimeToLive(key, String(userId), 31536000); } await this.redisService.deleteKey(`webauthn:register:${userId}`); // 已登录状态下可不必重签 token；如需刷新可在此签新 JWT return { verified: true, userId, credentialId: credentialIdB64url }; } } ``` > 你只需要实现（或补齐）`staffService.findManyCredentialsByUserId` 与 `upsertCredential` 两个数据存取方法；字段即你现有的 `credentialId/publicKey/counter/transports/userId`。 --- ## 时序对照（已登录绑定） 1. 前端带 **Authorization** 与 **X-Device-Id** → `POST /passkeys/register/options` 2. 后端从 **JWT** 取 `userId`，构造 **excludeCredentials**，保存 **challenge** 3. 前端调用 **`navigator.credentials.create({ publicKey })`** 4. 前端回传 **attestation + deviceIdentifier** → `/passkeys/register/verify` 5. 后端 **verify + 入库 + 设备唯一绑定** → 返回 `{ verified: true, userId }` --- ## 常见问题 - **为什么不让前端直接传 userId？** 防止伪造。登录态下应以 **Authorization** 为准，由后端解析身份。 - **若用户已绑定过此设备，再次点击绑定会怎样？** 由于 `excludeCredentials` 与 `dvc:owner:*` 绑定同时生效，**不会重复写入**；可返回幂等成功或提示“已绑定”。 - **如何与一键直登/JIT 流程共存？** - **未登录**：走 `/login/options` → 失败回退 `/register-or-login/*`。 - **已登录**：走本文 `/register/*`（绑定专用）。两套互不冲突。 --- ## 小结 - **唯一标识传递**：已登录场景下，把 **用户身份交给 JWT**，把 **设备唯一交给 `X-Device-Id`**。 - **绑定即注册**：本质是“已知用户”的注册流程；用 `excludeCredentials` 防重复，用 Redis 绑定 `deviceId -> userId`。 - **最少交互**：一次点击完成整个绑定，协议与登录/JIT 完全一致，维护成本低。 ]]> http://herong.info/posts/requirement-realization-2 http://herong.info/posts/requirement-realization-2 Fri, 05 Sep 2025 00:00:00 GMT userId` 绑定。 > 复杂逻辑均在代码**上一行加中文注释**。下面给出**整文件覆盖式代码**（符合你“Passkeys 项目优先给完整文件”的约定）。 --- ## 完整代码（直接替换你当前页面） ```vue ``` --- ## 说明与对接要点 - **后端路由**保持为： - `/passkeys/login/options` → 返回 `PublicKeyCredentialRequestOptions`（`challenge`/`allowCredentials[].id` 为 **base64url**）。 - `/passkeys/login/verify` → 接收 `packAssertion` 结果。 - `/passkeys/register-or-login/options` → 返回 `{ userId, options }`（注册用，`challenge`/`user.id` 为 **base64url**）。 - `/passkeys/register-or-login/verify` → 接收 `packAttestation` + `{ userId, deviceIdentifier }`。 - **设备唯一**：页面已在所有请求体中带上 `deviceIdentifier`（`this.deviceId`），你的服务端即可写入/校验 `dvc:owner:*`。 - **H5 前置条件**：需 HTTPS 或 `localhost`；Safari/移动端有平台限制。 - **App 端**：确保 `@/uni_modules/pass-keys` 已实现 `getPasskey`/`createPasskey` 且返回 **JSON 字符串**（与我们前面约定一致）。 需要我把 **“已登录场景的绑定按钮”** 也加到这个页面吗（即 `/passkeys/register/options|verify`，走绑定而非 JIT）？如果要，加哪个位置，我按你“只给改动段”的规范再补。 ]]> http://herong.info/posts/requirement-realization http://herong.info/posts/requirement-realization Fri, 05 Sep 2025 00:21:16 GMT 下面给出**可直接粘贴落地**的最小实现（HTML + JS）。 > 复杂逻辑的上一行均有中文注释。 > 假设你的后端路由与本文一致： > > - `/passkeys/login/options`、`/passkeys/login/verify` > - `/passkeys/register-or-login/options`、`/passkeys/register-or-login/verify` ### 1）页面与按钮 ```html 一键通行密钥

``` ### 2）前端模块：`passkeys-web.js` ```js // ======================= 基础工具 ======================= // 复杂：生成稳定的设备ID（首访生成并持久化，用于设备→账号绑定与风控） function getDeviceId() { const key = "device_id"; let id = localStorage.getItem(key); if (!id) { id = crypto?.randomUUID?.() || "dev-" + Date.now() + "-" + Math.random().toString(16).slice(2); localStorage.setItem(key, id); } return id; } // 复杂：base64url ↔ ArrayBuffer 转换，确保与后端统一 function b64urlToBuf(b64url) { const pad = "=".repeat((4 - (b64url.length % 4)) % 4); const b64 = (b64url + pad).replace(/-/g, "+").replace(/_/g, "/"); const str = atob(b64); const buf = new ArrayBuffer(str.length); const view = new Uint8Array(buf); for (let i = 0; i < str.length; i++) view[i] = str.charCodeAt(i); return buf; } function bufToB64url(buf) { const bytes = buf instanceof ArrayBuffer ? new Uint8Array(buf) : buf; let str = ""; for (let i = 0; i < bytes.length; i++) str += String.fromCharCode(bytes[i]); return btoa(str).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, ""); } // 复杂：把 AuthenticationOptions 中的 base64url 字段转 ArrayBuffer function toWebAuthnRequestOptions(serverOpts) { const opts = structuredClone(serverOpts); // challenge 需要转 ArrayBuffer if (typeof opts.challenge === "string") opts.challenge = b64urlToBuf(opts.challenge); // allowCredentials 中的 id 也需要转 ArrayBuffer if (Array.isArray(opts.allowCredentials)) { opts.allowCredentials = opts.allowCredentials.map((c) => ({ ...c, id: typeof c.id === "string" ? b64urlToBuf(c.id) : c.id, })); } return opts; } // 复杂：把 RegistrationOptions 中的 base64url 字段转 ArrayBuffer/Uint8Array function toWebAuthnCreationOptions(serverOpts) { const opts = structuredClone(serverOpts); if (typeof opts.challenge === "string") opts.challenge = b64urlToBuf(opts.challenge); if (opts.user && typeof opts.user.id === "string") opts.user.id = b64urlToBuf(opts.user.id); if (Array.isArray(opts.excludeCredentials)) { opts.excludeCredentials = opts.excludeCredentials.map((c) => ({ ...c, id: typeof c.id === "string" ? b64urlToBuf(c.id) : c.id, })); } return opts; } // 复杂：把 get() 结果打包成后端可验证的 JSON（按 WebAuthn 规范，全用 base64url） function packAssertion(cred) { const resp = cred.response; return { id: cred.id, rawId: bufToB64url(cred.rawId), type: cred.type, response: { clientDataJSON: bufToB64url(resp.clientDataJSON), authenticatorData: bufToB64url(resp.authenticatorData), signature: bufToB64url(resp.signature), userHandle: resp.userHandle ? bufToB64url(resp.userHandle) : null, }, clientExtensionResults: cred.getClientExtensionResults?.() || {}, }; } // 复杂：把 create() 结果打包成后端可验证的 JSON（按 WebAuthn 规范，全用 base64url） function packAttestation(cred) { const resp = cred.response; return { id: cred.id, rawId: bufToB64url(cred.rawId), type: cred.type, response: { clientDataJSON: bufToB64url(resp.clientDataJSON), attestationObject: bufToB64url(resp.attestationObject), }, clientExtensionResults: cred.getClientExtensionResults?.() || {}, }; } // 复杂：通用 POST 封装，自动带上设备ID async function postJSON(url, body) { const res = await fetch(url, { method: "POST", headers: { "content-type": "application/json", // 设备ID写入 Header，便于后端风控/设备绑定。后端也可从 body 读取。 "X-Device-Id": getDeviceId(), }, body: JSON.stringify(body || {}), credentials: "include", }); if (!res.ok) throw new Error(`${res.status} ${res.statusText}`); return res.json(); } // 复杂：检测“条件UI”与平台验证器可用性（仅做能力判断，不代表一定有凭据） async function detectSupport() { const hasWebAuthn = "PublicKeyCredential" in window; let conditional = false, uvpa = false; try { conditional = !!(await PublicKeyCredential.isConditionalMediationAvailable?.()); } catch {} try { uvpa = !!(await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable?.()); } catch {} return { hasWebAuthn, conditional, uvpa }; } // ======================= 业务主流程 ======================= // 复杂：优先尝试登录（可发现凭证/或定向 allowCredentials）；失败则自动转注册并登录 export async function oneTapPasskey(baseUrl = "") { const log = (msg) => { const pre = document.getElementById("log"); if (pre) pre.textContent += `[${new Date().toLocaleTimeString()}] ${msg}\n`; console.log(msg); }; const deviceId = getDeviceId(); const { hasWebAuthn, conditional, uvpa } = await detectSupport(); if (!hasWebAuthn) throw new Error("当前环境不支持 WebAuthn"); log(`检测：conditional=${conditional}, uvpa=${uvpa}`); try { // ========== 步骤A：请求“登录 options” ========== log("请求登录 options..."); const loginOptsResp = await postJSON(`${baseUrl}/passkeys/login/options`, { deviceIdentifier: deviceId, }); const requestOptions = loginOptsResp.options || loginOptsResp; // 兼容你的返回结构 const publicKey = toWebAuthnRequestOptions(requestOptions); // 复杂：若支持条件UI，则 mediation 设为 'conditional'；否则 'required'（需用户手势） const mediation = conditional ? "conditional" : "required"; // ========== 步骤B：发起 credentials.get ========== log(`调用 navigator.credentials.get (mediation=${mediation})...`); const assertion = await navigator.credentials.get({ publicKey, mediation }); // ========== 步骤C：打包并回传后端校验 ========== log("提交登录 verify..."); const verifyBody = packAssertion(assertion); const verifyResp = await postJSON( `${baseUrl}/passkeys/login/verify`, verifyBody ); log("登录成功 ✅ " + JSON.stringify(verifyResp)); return { mode: "login", result: verifyResp }; } catch (err) { // 复杂：常见失败 1）用户取消 2）设备没有匹配凭据 3）options 过期 console.warn("登录失败，准备转注册：", err); // ========== 步骤D：请求“一键注册 options” ========== const regOptsResp = await postJSON( `${baseUrl}/passkeys/register-or-login/options`, { deviceIdentifier: deviceId, } ); const { userId, options: creationOptionsServer } = regOptsResp.userId ? regOptsResp : { userId: regOptsResp.userId, options: regOptsResp.options }; const publicKey = toWebAuthnCreationOptions(creationOptionsServer); // ========== 步骤E：发起 credentials.create（注册） ========== log("调用 navigator.credentials.create ..."); const attestation = await navigator.credentials.create({ publicKey }); // ========== 步骤F：打包并回传后端，完成绑定+激活+登录 ========== log("提交注册 verify..."); const verifyBody = { ...packAttestation(attestation), userId, // 复杂：JIT 返回的临时/访客 userId deviceIdentifier: deviceId, // 复杂：用于设备→账号唯一绑定 }; const verifyResp = await postJSON( `${baseUrl}/passkeys/register-or-login/verify`, verifyBody ); log("注册并登录成功 ✅ " + JSON.stringify(verifyResp)); return { mode: "register-then-login", result: verifyResp }; } } // ======================= 页面挂载：按钮点击即触发 ======================= document.getElementById("btn-passkey")?.addEventListener("click", () => { // 复杂：这里的 baseUrl 请改为你的后端地址；同源部署可留空 oneTapPasskey("").catch((e) => { const pre = document.getElementById("log"); if (pre) pre.textContent += `❌ ${e?.message || e}\n`; console.error(e); }); }); ``` --- ## 与后端契约（对齐要点） - `/passkeys/login/options` - **入参**：`{ deviceIdentifier?: string }`（Header 也可） - **返回**：`{ options: PublicKeyCredentialRequestOptions }`（`challenge`、`allowCredentials[].id` 为 **base64url** 字符串） - `/passkeys/login/verify` - **入参**：上文 `packAssertion()` 的结果（所有字节字段 **base64url**） - **返回**：`{ verified: true, token, userId }` - `/passkeys/register-or-login/options` - **入参**：`{ deviceIdentifier?: string }` - **返回**：`{ userId: string, options: PublicKeyCredentialCreationOptions }`（`challenge`、`user.id`、`excludeCredentials[].id` 为 **base64url**） - `/passkeys/register-or-login/verify` - **入参**：`packAttestation()` + `{ userId, deviceIdentifier }` - **返回**：`{ verified: true, token, userId }` > 以上与您现有的 `PasskeysService` 设计完全兼容。你也可以在“已绑定设备”场景下返回 `allowCredentials`，以提升命中率（文中已说明）。 --- ## 常见问题（FAQ） - **能不能“先看一下本地有没有凭据”，有就登录、没有就不调后端？** 不能。浏览器不允许枚举凭据。你能做的只是能力探测与**尝试调用** `credentials.get`。而调用 `get/create` 都必须先有**服务端下发的 options（含 challenge）**。 - **什么时候用条件 UI（conditional mediation）？** 页面加载即拿到 `login options` 后即可“无提示等候”；但为简化，这里在**按钮点击**后再调，用 `mediation='conditional'`（若可用）+ `required` 作为兜底。 - **后端 challenge 过期怎么办？** 统一设置较短 TTL（如 300s），一旦 `get/create` 抛出 `InvalidStateError/NotAllowedError`，前端直接重拉 options 再试。 --- ## 测试步骤 1. **HTTPS 环境**部署（本地可用 `localhost`） 2. **确保后端 RP_ID/ORIGIN 正确**、Redis 正常、四个路由可达 3. 首次访问：点击按钮 → 预期走注册 → 后端 verify 成功后返回 token 4. 再次访问：点击按钮 → 直接 `get()` 登录成功 5. Android/Chrome 测试条件 UI：地址栏出现通行密钥提示；Safari 需同源 HTTPS --- ## 小结 - “先判断本地是否有凭据”在浏览器上**不可行**； - **正确做法**是**每次先拿登录 options**，用 `credentials.get` 尝试登录； - **失败则无缝切到注册**（JIT 建号 + 可发现凭证 + 注册即登录）。 - 上文代码开箱即用，你只需要把 `baseUrl` 指向你的后端即可。 ]]> http://herong.info/posts/数值安全判断 http://herong.info/posts/数值安全判断 Wed, 23 Sep 2026 11:45:26 GMT 🔸 `Number.isNaN()` / `Number.isFinite()` —— 不转换，更安全； > 🔸 全局的 `isNaN()` / `isFinite()` —— 会强转字符串，容易误判； > 🔸 `typeof x === 'number'` —— 只看类型，不代表值有效。 ]]> http://herong.info/posts/数值输入框与中文输入法（IME）合成态的最佳实践 http://herong.info/posts/数值输入框与中文输入法（IME）合成态的最佳实践 Thu, 23 Oct 2025 00:00:00 GMT 说明：只给**需要修改**的片段，并在修改处上一行加中文注释（符合你的偏好）。 > 目标：合成中只缓存字符串；合成结束统一 finalize；合成中禁用键盘/滚轮/连发步进。 ### A. `useNumericInteractions.ts`（合成态处理 & 交互兜底） ```ts // —— 输入/合成 —— // const handleInput = (val: string) => { // ✅ 合成中：仅接受中间态字符串，绝不做解析/格式化/校验 bridge.setFromString(val, { acceptIntermediate: true }); }; const onCompositionStart = () => { isComposing.value = true; }; // ✅ 合成结束：立刻用最终字符串跑一次完整流程（解析→校验→格式化） const onCompositionEnd = (e?: CompositionEvent) => { isComposing.value = false; const finalStr = (e?.target as HTMLInputElement | undefined)?.value ?? bridge.formattedValue.value ?? ""; // 在这里走“非中间态”路径，触发解析与格式化 bridge.setFromString(finalStr); bridge.finalize(); }; // —— 滚轮 —— // const onWheel = useThrottleFn((e: WheelEvent) => { // ✅ 合成中禁止滚轮更改，避免干扰候选框滚动或误操作 if (isComposing.value) return; if (opts.enableWheel === false) return; if (opts.preventWheelDefault) e.preventDefault(); const m = getMultiplierFromEvent(e, accelerateFactors.value); bump(e.deltaY < 0 ? +m : -m); }, opts.wheelThrottleMs ?? 16); // —— 长按连发 —— // function startSpin( dir: 1 | -1, ev?: MouseEvent | PointerEvent | KeyboardEvent | TouchEvent ) { // ✅ 合成中先 finalize，再允许步进（也可选择直接 return） if (isComposing.value) { isComposing.value = false; bridge.finalize(); } if (opts.enableSpin === false) return; // ……（原逻辑保持不变） } // —— 键盘 —— // const onKeydown = useThrottleFn((e: KeyboardEvent) => { // ✅ 合成中禁用键盘步进（方向键/翻页键），避免抢占输入法按键 if (isComposing.value || (e as any).isComposing) return; if (opts.enableKeyboard === false) return; // ……（原逻辑保持不变） }, 24); ``` ### B. `useNumericCore.ts`（实现真正的“中间态”分支） 你已经预留了 `acceptIntermediate` 参数，但相关代码被注释掉，导致**合成中仍然走完整 pipeline**。请恢复并稍作增强： ```ts const setFromString = ( input: string, opts?: { acceptIntermediate?: boolean } ) => { // ✅ 合成中：只更新 formattedValue；若 parse 得到合法数值，可“悄悄”同步 rawValue，但不触发校验/格式化 if (opts?.acceptIntermediate) { // 在合成中保持用户所见即所得 core.state.formattedValue = input; // 仅当能稳定解析为有限数时，更新 rawValue；否则置空，表示“未定” const parsed = core.options.parseFn?.(input, core.options); if (parsed != null && Number.isFinite(parsed)) { core.state.rawValue = parsed; } else { core.state.rawValue = null; } // 中间态不判错，避免红字抖动 core.state.isValid = true; core.state.errors = []; // ✅ 必须同步一次，让 UI 即时显示合成中的字符串 sync(); return; } // ✅ 非中间态：走核心 setValue（可触发解析/校验/格式化等完整流程） core.setValue(input, false); // 之前这里是 sync(false) —— 会造成 UI 不更新。应改为同步。 // 在微任务中批量合并，避免抖动 sync(); }; ``` > 这样配合上 `onCompositionEnd` 的 `finalize()`，就能保障： > **合成中：只显示输入法正在编辑的文本**；**结束时：一次性格式化为数值**。 --- ## 为什么要“忽略合成中的值” 1. **打断候选体验**：格式化（加千分位、截断小数、自动纠正范围等）会改动字符串与光标位置，直接把输入法**候选区冲掉或错位**。 2. **错误信号噪声**：合成中会出现字母/拼音/空串等非数值字符，若立刻校验会产生**闪烁的错误提示**。 3. **键位冲突**：`ArrowUp/Down`、`PageUp/Down` 在合成中通常用于候选选择或移动，**不该触发步进**。 4. **跨端差异**：不同浏览器/IME 的事件时序不同，**同时依赖 `e.isComposing` 与本地标记**更稳。 --- ## 实施清单（Best Practices） 1. **判定条件**：`if (localComposing || e.isComposing) return;` 2. **中间态策略**： - 仅 `formattedValue = input`；可尝试解析，**但不显示错误**，不强制格式化。 - 同步 UI，保证“所见即所得”。 3. **结束态策略**： - `compositionend` 里用最终字符串 `setFromString(final)` → `finalize()`。 - 再下一次 `input[!isComposing]` 发生也应安全（幂等）。 4. **交互屏蔽**： - 合成中禁用：滚轮、键盘步进、长按连发；或先 `finalize()` 再执行（视产品决策）。 5. **受控模式防抖**： - 合成中**不要**被外部的 `modelValue` 变更覆盖当前输入串（在组件层用 `composing` 锁即可）。 6. **空值处理**： - 合成结束若为空串，`finalize()` 可按 `defaultValue` 或 `null` 策略统一处理（你已有 `reset`/`formatValue` 可用）。 7. **格式化与光标**（进阶）： - 若需要即时千分位效果，建议在**非合成态**进行，并实现“光标映射”以保留 caret 位置（难点，可后续迭代）。 --- ## 参考实现片段（组件层建议） ```vue ＋ － ``` --- ## 测试用例矩阵（强烈建议跑一遍） - **浏览器 × IME**：Chrome/Edge/Firefox/Safari × 微软拼音/搜狗/QQ 拼音/macOS 简体/繁体/移动端 Gboard。 - **场景**： 1. 拼音合成中连续输入字母，检查是否无格式化、无错误闪烁； 2. 合成结束立即格式化（小数点、千分位、范围裁剪、精度对齐）； 3. 合成中按 `↑/↓/PgUp/PgDn` 不应步进； 4. 合成中滚轮不应改变值； 5. 单击/长按步进键时，若处于合成态，是否先完成合成再步进； 6. 删除为**空串**并失焦（或回车）时的最终值策略是否符合预期。 --- ## 常见坑位 - **仅依赖 `e.isComposing`**：部分环境不稳定，务必配合本地 `isComposing` 标记。 - **合成中仍然 `setValue`**：会触发格式化/校验，导致光标跳动与候选丢失。 - **`sync(false)` 关闭同步**：导致 UI 不更新，用户看不到正在输入的字符串（已在上文修正）。 - **滚轮默认行为**：在输入框上滚动应谨慎，建议提供 `enableWheel`、`preventWheelDefault` 与“仅聚焦时有效”的策略。 --- ## 总结 你的数值输入框在合成态应**完全尊重输入法的编辑过程**：**只显示字符串，不做数值语义处理**；在合成结束的瞬间**一次性**完成解析/校验/格式化与同步。按上述两处“最小修改”，即可实现稳定、跨端一致而不打扰中文输入的体验。 ]]> http://herong.info/posts/显式覆盖 http://herong.info/posts/显式覆盖 Fri, 05 Sep 2025 21:13:27 GMT 复杂逻辑：将“是否需要鉴权”收敛为**实例级默认值** + **URL 前缀** + **每次请求的显式覆盖**。 **删除：** ```ts // 删除这行 const noAuthPaths = [ "/login", "/register", "/public-endpoint", "/api/pub/get_feednews", ]; ``` **在 `createAxiosHttp` 定义处新增第二个参数（不改已有调用方也能有默认值）：** ```ts // 复杂逻辑：通过 opts 控制默认鉴权与公开前缀 function createAxiosHttp( config: AxiosRequestConfig, opts: { authDefault?: boolean; publicPrefixes?: string[] } = {}, ) { const authDefault = opts.authDefault ?? true const publicPrefixes = opts.publicPrefixes ?? ['/api/pub'] // 仅维护“前缀”，而非逐个接口 // ... ``` **在请求拦截器里替换 needAuth 判定：** ```ts _axios.interceptors.request.use((req) => { // ...（保留你已有的 AbortController 代码） // 复杂逻辑：先按前缀判定是否公开，再由显式 req.auth 覆盖 const url = req.url || ""; const isPublicByPrefix = publicPrefixes.some((p) => url.startsWith(p)); // 复杂逻辑：优先使用 req.auth（true/false），否则用实例默认值 + 前缀约定 const needAuth = (req as any).auth ?? (authDefault && !isPublicByPrefix); const accToken = storage.get(ACCESS_TOKEN); const tokenType = storage.get(TOKEN_TYPE) || "Bearer"; if (needAuth && !accToken) { ((req as any).__abortController as AbortController | undefined)?.abort(); return Promise.reject(new Error("UNAUTHENTICATED")); } if (needAuth && accToken) { req.headers = { ...req.headers, Authorization: `${tokenType} ${accToken}` }; } return req; }); ``` **创建实例时传入前缀约定（一次配置，全局生效）：** ```ts // 复杂逻辑：默认需要鉴权，唯独 /api/pub/** 前缀走公开 const http = createAxiosHttp( { timeout: 10000, baseURL: API_BASE, withCredentials: true, xsrfCookieName: "Authorization", xsrfHeaderName: "Authorization", }, { authDefault: true, publicPrefixes: ["/api/pub"] } ); ``` ### 2) 显式覆盖个别公开接口（例如登录/注册） > 复杂逻辑：无需继续维护数组；在调用时给 `{ auth:false }`。 ```ts // 复杂逻辑：显式声明无需鉴权 http.request("/auth/login", "POST", body, { auth: false }); http.request("/auth/register", "POST", body, { auth: false }); ``` ### 3) 小修 bug：统一释放键，避免内存泄露 > 你在请求里写的是 `__abortController`，但错误拦截里读取的是 `__ac`。统一成同一个键。 **在错误拦截器里替换：** ```ts // 复杂逻辑：统一用 __abortController const abortController = (err?.config as any)?.__abortController as | AbortController | undefined; if (abortController) abortPool.delete(abortController); ``` --- ## 为什么这是“更像大厂”的做法 - **约定 > 配置**：接口分层（`/api/pub/**` 公开，其他默认鉴权）是**稳定、低维护**的组织方式；新增公开接口只需放在该前缀下。 - **按需覆盖**：极少数“路径不在公开前缀但仍需公开”的接口，用 `auth:false` **显式声明**，可读性强。 - **可扩展**：未来要拆网关/多后端时，可用**双实例**进一步隔离（见下方“进阶”）。 - **类型友好**：`AxiosRequestConfig` 扩展 `auth?: boolean`，IDE 自动提示，避免遗漏。 --- ## 进阶可选（按需采纳） ### 方案 B：双实例隔离（最常见于中大型前端） > 公有与鉴权接口**不同实例**，互不影响，拦截器更简单。 ```ts // 复杂逻辑：一个实例默认鉴权，一个实例默认公开 export const authHttp = createAxiosHttp(config, { authDefault: true, publicPrefixes: [], }); export const pubHttp = createAxiosHttp(config, { authDefault: false, publicPrefixes: ["/api/pub"], }); // 使用时不再传 auth:false pubHttp.request("/api/pub/get_feednews", "GET"); authHttp.request("/api/secure/profile", "GET"); ``` ### 方案 C：API 分层封装（类型安全） > 给每个后端接口包一层函数：在函数里固定 `auth:true/false`，业务层不再关心 `auth`。 ```ts // 复杂逻辑：在 API 层固定鉴权语义 export const Api = { getFeedNews: () => http.request("/api/pub/get_feednews", "GET", undefined, { auth: false, }), getProfile: () => http.request("/api/secure/profile", "GET"), // 默认为鉴权 }; ``` --- ## 小结 - **最佳实践**：**前缀约定 + 显式覆盖**，别再维护接口白名单数组。 - 这样新增公开接口只要放到 `/api/pub/**`，其余默认鉴权；个别例外 `auth:false` 即可。 - 若项目更复杂，进一步采用**双实例**或**API 分层**，把鉴权语义固化到“调用入口”，彻底杜绝分散判断。 ]]> http://herong.info/projects/ai-chat http://herong.info/projects/ai-chat Wed, 23 Sep 2026 11:45:26 GMT http://herong.info/projects/aurumchart http://herong.info/projects/aurumchart Wed, 23 Sep 2026 11:45:26 GMT http://herong.info/projects/enterprise-platform http://herong.info/projects/enterprise-platform Wed, 23 Sep 2026 11:45:26 GMT http://herong.info/projects/minicodex http://herong.info/projects/minicodex Wed, 23 Sep 2026 11:45:26 GMT http://herong.info/projects/shopthrive http://herong.info/projects/shopthrive Wed, 23 Sep 2026 11:45:26 GMT http://herong.info/projects/trading-system http://herong.info/projects/trading-system Wed, 23 Sep 2026 11:45:26 GMT http://herong.info/posts/AI-协作与边界/AI 时代技能谱系：广而杂还是深而稳？——给在职开发者的「反替代」路线图 http://herong.info/posts/AI-协作与边界/AI 时代技能谱系：广而杂还是深而稳？——给在职开发者的「反替代」路线图 Sun, 14 Sep 2025 00:00:00 GMT 判断是否该“学得更杂”的准绳：你是否经常**卡在边界**（网关/鉴权/数据质量/部署/观测/合规）？如果是，说明需要“补相邻面”。 ## 2. 单一技能会被 AI 取代吗？ ### “自动化风险五问”（答“是”的越多，风险越高） 1. 需求是否**高度标准化**（几乎不与人沟通）？ 2. 输入输出是否**完全可量化**（像打分题）？ 3. 是否有**充足历史样本**可供模型拟合？ 4. 验收是否**单指标**就能定胜负（例如准确率阈值）？ 5. **合规与安全要求低**（错了成本也不高）？ **高风险示例**：纯 CRUD、简单切图、常见脚手架/迁移、无上下文的“写单元测试”。 **低风险示例**：含**需求沟通与取舍**、**跨系统约束**、**性能/成本与 SLO**、**现场应急与灰度回滚**、**数据与合规治理**的工作。 > 你的“护城河”应落在**难以标准化**的环节：需求澄清、系统设计、成本/性能权衡、数据与安全、上线与可观测、口述解释与知识迁移。 ## 3. 广学 ≠ 乱学：用 **T/π 形**规划相邻面 ### 3×3 能力面板（示例） - **深根（选 1–2 条）**：如前端工程化/可观测、后端高并发/数据一致性、GIS/地图与空间索引、AI 检索/RAG。 - **相邻面（选 2–4 个）**：云部署（容器/CI/CD）、数据工程（ETL/质量）、安全与合规（鉴权/审计/隐私）、AI 评测与成本治理。 - **通用底座**：网络/OS/数据库基础、系统设计沟通、度量与实验。 ### 90 天“相邻栈”拓展法（按周产物驱动） - **每 2 周**选择一个“业务化小题”：必须交付 **在线 Demo + 自动评测 + 走查视频**。 - **每次拓展只加一跳**：例如你的深根是前端 → 相邻：RAG 接入 → 再相邻：检索评测与观测 → 再相邻：低成本推理与缓存。 - **用“证据化简历”积木**：每个积木包含问题、约束、指标、权衡与结果图表。 ## 4. 为什么 AI 在“新技术”上更不准？怎么避坑？ **原因** - **训练滞后**：模型更新不及生态演进。 - **语料稀疏**：新框架/新版本案例少、歧义多。 - **官方语义易变**：参数名/默认值/兼容策略频繁改。 - **错因难察**：模型会“自洽”地补全缺失事实（幻觉）。 **四重校验法**（从低信到高信） 1. **营销/技术分享**（仅作线索） 2. **官方文档与 Release Notes**（版本边界为王） 3. **源码与官方示例/测试**（真相在 tests/） 4. **最小可复现实验**（容器化、锁版本、保留日志与指标） **带置信度的提问模板**（贴给 AI，用于新技术检索） ```text 你将回答一个可能涉及新版本/新库的问题。要求： 1) 若你不确定或缺语料，请明确输出【未知】并停在这里，不要编造。 2) 给出“你确定的部分”的最小示例，并标注版本前提（库名@版本）。 3) 附上你建议的验证步骤清单（我会用最小容器验证）。 问题是：<在此粘贴我的问题>。 ``` **最小可复现实验模板（MRE）** ```bash # 1) 创建隔离环境并锁版本 mkdir mre && cd mre # 用你常用的包管理器/容器，统一输出版本 # 2) 复制最小代码，记录命令与日志 # 3) 保存 benchmark/指标到 artifacts/ 目录（便于复查与对比） ``` ## 5. 面向在职者的“反替代”清单（可直接执行） - **每周 1 次走查**：选择一段最近改过的核心代码，用 10 分钟口述：背景 → 约束 → 方案 → 权衡 → 指标。 - **每周 1 个边界点**：在鉴权、缓存、限流、观测、灰度中选一个做“最小实验”，写下复盘。 - **每季度 1 个“业务化”作品**：必须可在线访问，有指标截图与成本分析。 - **AI 使用日志**：保留 prompt、版本、你做的修改与验证结论，形成**过程证据**。 - **技术雷达看板**（观望/试点/采用/放弃四象限），每月更新一次。 示例雷达（YAML） ```yaml adopt: - "RAG 线上评测（准确率/延迟/成本/安全）" - "可观测三件套（日志/指标/追踪）" trial: - "函数级缓存 + Token 限额联动" - "前端 A/B + 合成监控" assess: - "Agent 工作流（以特定业务为锚）" - "向量数据库 X 与 Y 的冷热分层" hold: - "仅换皮的脚手架替换" ``` ## 6. “广度”怎么选？——三个优先级原则 1. **靠近现金流**：优先学能直接降低成本/提升转化/缩短交付的东西（如观测、评测、缓存、灰度与成本治理）。 2. **靠近你的深根**：相邻一跳最划算，跨三跳成本陡增。 3. **可证据化**：能用指标与 Demo 证明价值的学习，才会沉淀为“护城河”。 ## 7. 给你的个性化建议（结合你之前的方向） 你长期做前端/全栈与地图相关工作，也在搭建 AI 相关功能。建议的 π 形组合示例： - **深根 A**：前端工程化 + 可观测（含性能与体验指标）。 - **深根 B**：RAG 与检索评测（与地图/知识检索联动）。 - **相邻面**：数据治理（质量/去重/标注）、鉴权与审计、成本治理（缓存/批处理/降级）、GIS 空间索引与切片服务。 - **落地路线**：用你现有站点做“AI + 地图知识库”项目，从**指标化问答**（正确率/延迟/成本）入手，逐步加入**合规与安全检查**。 ## 8. 一句话记忆法 - **深耕 1–2 条可度量的护城河**，再**串起 2–4 个相邻面**； - **每两周一个“线上可验证”的小成果**； - **让 AI 当陪练，而非代写**； - **新技术一律“四重校验 + MRE”过闸**。 ]]> http://herong.info/posts/AI-协作与边界/AI-时代：工程师不可替代的价值与协作边界 http://herong.info/posts/AI-协作与边界/AI-时代：工程师不可替代的价值与协作边界 Tue, 09 Sep 2025 00:00:00 GMT http://herong.info/posts/AI-协作与边界/ArkTS（HarmonyOS）版 SSE 解析器·最小实现（作为 WS 失败后的回退） http://herong.info/posts/AI-协作与边界/ArkTS（HarmonyOS）版 SSE 解析器·最小实现（作为 WS 失败后的回退） Tue, 14 Oct 2025 00:00:00 GMT 只给**需要新增/修改的代码片段**；复杂逻辑上方已加中文注释。 > 作用：当 **WebSocket** 连接失败时，使用 **`fetch + ReadableStream`** 解析 `text/event-stream`，逐块追加到对话文本。 ## 一、新增：通用 SSE 解析器（ArkTS 文件，例如 `entry/src/main/ets/common/sseClient.ets`） ```ts // ✅ 新增文件：common/sseClient.ets // 【复杂逻辑】逐行解析 text/event-stream（SSE）：以空行 \n\n 作为帧边界，提取以 "data: " 开头的行。 // 运行前会检测环境是否支持 fetch+ReadableStream（HarmonyOS 新版有；旧版不支持则直接抛错给上层回退 HTTP）。 export async function startSSEStream( url: string, { onData, // 每个 data: 帧的文本增量 onDone, // 收到 [DONE] 或流结束 onError, // 发生异常 headers, // 可选：额外请求头 signal // 可选：AbortSignal，用于取消 }: { onData: (chunk: string) => void; onDone?: () => void; onError?: (err: Error) => void; headers?: Record; signal?: AbortSignal; } ): Promise { // 【复杂逻辑】能力检测：ReadableStream 在部分 HarmonyOS 版本不可用 const hasFetch = typeof (globalThis as any).fetch === 'function'; const canStream = !!(globalThis as any).ReadableStream; if (!hasFetch || !canStream) { throw new Error('SSE 不受当前运行环境支持（缺少 fetch/ReadableStream）'); } let response: Response | undefined; const decoder = new TextDecoder('utf-8'); // 处理 UTF-8 半字符切片 let buffer = ''; // 帧缓冲 try { response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', ...(headers || {}) }, // 注意：SSE 接口常为 POST + JSON 入参；若你的后端不需要请求体，可去掉 body body: JSON.stringify({ /* 占位：实际调用时由上层传参 */ }), signal }); if (!response.ok || !response.body) { throw new Error(`SSE HTTP ${response.status}`); } const reader = response.body.getReader(); while (true) { // 【复杂逻辑】逐块读取与解码，避免中文被截断 const { value, done } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); // 解析帧：SSE 以空行 \n\n 结帧 const frames = buffer.split('\n\n'); buffer = frames.pop() || ''; for (const frame of frames) { // 每帧可能包含多行（event/id/data 多行） const lines = frame.split('\n'); for (const line of lines) { // 只处理 data: 行；其它如 event:/id: 可按需扩展 if (line.startsWith('data:')) { const payload = line.slice(5).trim(); if (payload === '[DONE]') { onDone && onDone(); try { reader.cancel(); } catch {} return; } onData(payload); } } } } // 流正常结束 onDone && onDone(); } catch (err) { onError && onError(err as Error); // 外层会做回退，不再抛出 } finally { // 无需额外关闭，fetch/ReadableStream 自行回收 } } ``` > 说明：这里把 **POST** 当作默认发法以匹配你后端 `/ai/scenario-dialog/stream`；如果你的流式接口是 **GET**，把 `method/body` 去掉即可。 --- ## 二、在页面里接入（`ScenarioDialogPage.ets`） ### 1) 顶部导入 ```ts // ✅ 新增：引入刚才的 SSE 客户端 import { startSSEStream } from '../common/sseClient'; ``` ### 2) 新增：SSE 回退调用封装 ```ts // ✅ 新增：SSE 回退（仅在 WS 失败时使用） // 【复杂逻辑】和 WS 一样做“缓冲 + 合并刷新”，避免每个 token 刷一帧导致卡顿。 // 这里兼容你现有的 BASE_URL 与历史裁剪策略。 async callAIStreamSSE(userMessage: string, onDelta: (t: string) => void): Promise { // 仅传最近 10 条历史，减少负载 const historyPayload = this.dialogMessages.slice(-10).map((m) => ({ role: m.role, content: m.content })); // Abort 控制，便于用户中断 const ctrl = new AbortController(); // —— 节流合并策略 —— // let acc = ''; let rafId: number | null = null; let lastFlush = Date.now(); const flush = () => { if (!acc) return; const now = Date.now(); // 【复杂逻辑】最小片段阈值 + 标点触发 + 最大等待 200ms const small = acc.length < 6 && (now - lastFlush) < 80; const punct = /[，。！？\n]/.test(acc); const timeout = (now - lastFlush) > 200; if (!small || punct || timeout) { onDelta(acc); acc = ''; lastFlush = now; } else { if (!rafId) { rafId = requestAnimationFrame(() => { rafId = null; flush(); }); } } }; // 发送到你后端的 SSE 流式端点 const url = `${BASE_URL}/ai/scenario-dialog/stream`; await startSSEStream(url, { onData: (chunk: string) => { acc += chunk; flush(); }, onDone: () => { // 收尾：把残余缓冲刷掉 if (acc) { onDelta(acc); acc = ''; } }, onError: (_err: Error) => { // 交给上层进一步回退（一次性 HTTP） if (acc) { onDelta(acc); acc = ''; } }, headers: { // 你的后端需要 JSON 请求体，这里把参数放到 body（见下方 startSSEStream 调整） // 但 startSSEStream 默认空体，这里通过 signal 标识，我们稍后用“重载调用”写法传参 'Accept': 'text/event-stream' }, signal: ctrl.signal }); } ``` > **重要**：上面 `startSSEStream` 里默认把 `body` 写成空对象。为了把 `scenario/message/history` 传过去，我们**建议在发起前对 `startSSEStream` 做一次“重载调用”**（见下一段“③ 修改：把请求体带上”）。 ### 3) 修改：带请求体调用 `startSSEStream`（在页面里 patch 一下调用） ```ts // ✅ 修改：在调用前，临时“包装” startSSEStream，把业务 JSON 放在 body 里。 // 这样你不用改 sseClient.ets 的公共签名。 async callAIStreamSSE(userMessage: string, onDelta: (t: string) => void): Promise { const historyPayload = this.dialogMessages.slice(-10).map((m) => ({ role: m.role, content: m.content })); const ctrl = new AbortController(); let acc = ''; let rafId: number | null = null; let lastFlush = Date.now(); const flush = () => { /* 与上文相同，省略 */ }; const url = `${BASE_URL}/ai/scenario-dialog/stream`; // —— 这里临时“内联”一个带 body 的 fetch，直接复用解析逻辑 —— // const hasFetch = typeof (globalThis as any).fetch === 'function'; const canStream = !!(globalThis as any).ReadableStream; if (!hasFetch || !canStream) { throw new Error('SSE 不受当前运行环境支持'); } const decoder = new TextDecoder('utf-8'); let buffer = ''; const resp = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'text/event-stream' }, body: JSON.stringify({ scenario: this.currentScenario, message: userMessage, history: historyPayload }), signal: ctrl.signal }); if (!resp.ok || !resp.body) { throw new Error(`SSE HTTP ${resp.status}`); } const reader = resp.body.getReader(); while (true) { const { value, done } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const frames = buffer.split('\n\n'); buffer = frames.pop() || ''; for (const frame of frames) { const lines = frame.split('\n'); for (const line of lines) { if (line.startsWith('data:')) { const payload = line.slice(5).trim(); if (payload === '[DONE]') { if (acc) { onDelta(acc); acc = ''; } return; } acc += payload; flush(); } } } } if (acc) { onDelta(acc); acc = ''; } } ``` --- ## 三、把 SSE 回退插到发送链路里 > 在你已有的 `handleSendMessage()` 中，**WS 优先**；若抛错，则**尝试 SSE**；再失败，回退到一次性 HTTP（你已有的 `callAI()`）。 ```ts // ✅ 仅展示需要替换的片段：将 “WS 失败 → 回退 HTTP” 扩展为 “WS 失败 → SSE → HTTP” async handleSendMessage() { const text = this.inputText.trim(); if (!text) return; this.dialogMessages.push(this.createMessage('user', text)); this.inputText = ''; const idx = this.dialogMessages.push(this.createMessage('ai', '')) - 1; let acc = ''; const applyDelta = (chunk: string) => { acc += chunk; this.dialogMessages[idx] = this.createMessage('ai', acc); }; try { // 1) 优先 WebSocket 流式 await this.callAIStreamWS(text, applyDelta); return; } catch (_e1) { // 2) 回退 SSE try { await this.callAIStreamSSE(text, applyDelta); return; } catch (_e2) { // 3) 最后回退一次性 HTTP try { const reply = await this.callAI(text); this.dialogMessages[idx] = this.createMessage('ai', reply); return; } catch (_e3) { this.dialogMessages[idx] = this.createMessage('ai', '抱歉，服务暂时不可用，请稍后再试~'); return; } } } } ``` --- ## 四、注意事项（HarmonyOS/ArkTS 实战） * **ReadableStream 支持**：部分 HarmonyOS 版本/设备不提供 `fetch().body` 流式读取能力；上文代码已做**能力检测**，不支持时会抛错交给上一层回退。 * **超时与取消**：通过 `AbortController` 即可主动**中断当前 SSE**；用户改问题时要调用 `controller.abort()`。 * **Nginx 配置**：SSE location 继续保持 `proxy_buffering off`、`add_header X-Accel-Buffering no;`、`proxy_read_timeout 600s`。 * **频繁渲染**：务必使用**缓冲 + 合并刷新**（上文的最小片段阈值/标点触发/最大等待 + rAF），否则 UI 会抖动且耗电。 * **编码**：必须用 `TextDecoder(stream:true)`，否则中文容易出现乱码或半个字。 --- 如果你确认设备/系统版本**不支持 ReadableStream**，我可以再给一版“**伪 SSE（短轮询）**”的最小适配：后端暴露 `/ai/scenario-dialog/poll`，前端每 300ms 拉一次“未读增量”，体验也能接近流式（比一次性强不少）。需要的话告诉我。 ]]> http://herong.info/posts/AI-协作与边界/ChatGPT Scheduled + Secure MCP Tunnel 个人操作手册 http://herong.info/posts/AI-协作与边界/ChatGPT Scheduled + Secure MCP Tunnel 个人操作手册 Wed, 23 Sep 2026 11:45:26 GMT B["ChatGPT Developer Mode App"] B --> C["OpenAI Secure MCP Tunnel"] C --> D["本地 NestJS MCP Server"] D --> E["MySQL 人工审核 staging"] ``` | 名称 | 作用 | 改 MCP 工具时是否重建 | | --- | --- | --- | | ChatGPT Pro | 运行 Scheduled 和 ChatGPT 会话 | 否 | | Runtime API Key | 让 `tunnel-client` 连接 OpenAI Tunnel 控制面 | 否 | | `tunnel_id` | 标识已经创建的 Secure MCP Tunnel | 否 | | Developer Mode App | ChatGPT 中看到的“码圈一分钟·入库测试” | 通常只 Refresh；刷新入口缺失时才重建 App | | MCP 工具 | NestJS 服务通过 `tools/list` 暴露的能力 | 改后重启后端并 Refresh App | | Scheduled 任务 | 决定何时搜索、生成 JSON 和调用 MCP | 调试和正式阶段可分别创建或调整 | 最容易混淆的是： - API Key 不是工具； - App 名也不是工具名； - App 卡片只显示“码圈一分钟·入库测试”，进入详情后才会看到工具； - 工具名由 NestJS MCP Server 决定。 当前应看到两个工具： ```text get_maquan_connection_status submit_maquan_scheduled_brief_for_review ``` 其中： - `get_maquan_connection_status`：只读连接检查，不访问审核数据库，不产生入库记录； - `submit_maquan_scheduled_brief_for_review`：写入人工审核 staging，按 `runId` 幂等，不发布、不审核、不创建 Gold；输入和输出都提供 JSON Schema，便于 Scheduled 稳定识别 accepted、duplicate 和安全错误。 ### 1.1 ChatGPT 是怎样发现这两个工具的 先记住结论：ChatGPT 不会扫描本机端口、Git 仓库、NestJS 代码或数据库；提示词也不能创建 MCP 工具。工具发现发生在“创建或 Refresh Developer Mode App”时。 ```mermaid sequenceDiagram participant U as 用户 participant C as ChatGPT Developer Mode App participant T as OpenAI Secure MCP Tunnel participant TC as 本机 tunnel-client participant N as NestJS MCP Endpoint U->>C: 创建或 Refresh App，并选择已有 Tunnel C->>T: 连接所选 tunnel_id T->>TC: 把 MCP 请求转到已连接的客户端 TC->>N: 转发到 mcp_target C->>N: MCP initialize C->>N: MCP tools/list N-->>C: 返回工具名、描述、schema、annotations 和 metadata C-->>U: 在 App 详情的 Actions 中显示两个工具 ``` 对本项目来说，完整发现链路是： 1. NestJS 通过 MCP SDK 的 `server.registerTool(...)` 注册两个工具； 2. NestJS 把 MCP 协议端点暴露在 `POST /api/v1/external-teacher/mcp`； 3. `maquan-local` profile 的 `mcp_target` 指向这个本地地址； 4. `tunnel-client run --profile maquan-local` 主动建立到 OpenAI Secure MCP Tunnel 的连接； 5. 在 ChatGPT 创建 App 时选择这个 Tunnel，相当于把 App 与该转发通道关联起来； 6. ChatGPT 通过通道完成 MCP 初始化并发出 `tools/list`； 7. NestJS MCP SDK 根据 `registerTool` 返回两个工具的定义； 8. ChatGPT 保存这份 App metadata，App 详情中的 `Actions` 就来自这次返回； 9. 后端以后新增、删除或修改工具时，重启后端并点击 `Refresh`，ChatGPT 才会重新读取 `tools/list`。 本项目已经用 HTTP 集成测试验证了这三个协议动作： ```text initialize -> tools/list -> tools/call ``` 因此，ChatGPT 详情页里出现 `get_maquan_connection_status`，不是因为 Scheduled 提示词里写了这个名字，而是因为后端已经注册它，ChatGPT 在创建或 Refresh App 时通过 `tools/list` 读到了它。 ### 1.2 到点运行时，ChatGPT 怎样调用工具 “发现工具”和“调用工具”是两件事： ```mermaid flowchart LR A["Scheduled 到点运行"] --> B["模型按任务指令检索并生成 JSON"] B --> C["模型从已连接 App 的工具 metadata 中选择写工具"] C --> D["ChatGPT 发送 tools/call + brief 参数"] D --> E["Tunnel 转发到 NestJS MCP Endpoint"] E --> F["MCP handler 调用 ingestFromMcp"] F --> G["校验、runId 幂等、写入人工审核 staging"] G --> H["返回 accepted 或 duplicate"] ``` 模型决定是否使用工具时，主要能看到并利用： - App 的 Name 和 Description； - 工具的 name、title 和 description； - input schema 与 output schema； - `readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint` 等 annotations； - 当前 Scheduled 提示词对调用时机、参数和次数的明确要求； - 用户为该 App 选择的 Permissions。 提示词的职责是要求模型在正确时间选择正确工具、传入完整 `brief` 并且只调用一次。它不能让一个后端未注册的工具凭空出现，也不能替代 schema、权限或后端校验。 ### 1.3 后端必须做哪些事情 | 后端职责 | 本项目实现 | 为什么需要 | | --- | --- | --- | | 提供 MCP HTTP 入口 | `scheduled-brief-mcp.controller.ts` | 接收 MCP JSON-RPC 请求，并交给 Streamable HTTP transport | | 注册和声明工具 | `scheduled-brief-mcp.server.ts` 中的 `server.registerTool(...)` | 让 `tools/list` 能返回可发现的工具定义 | | 提供清晰 metadata | name、title、description、input/output schema、annotations、`_meta` | 让模型正确选工具、正确传参，并让 ChatGPT 进行权限判断和状态展示 | | 实现只读探针 | `get_maquan_connection_status` | 创建任务前可以验证连通性且不产生数据库记录 | | 实现受限写入 | `submit_maquan_scheduled_brief_for_review` | 只接收完整 `maquan-scheduled-brief-v1` 并进入人工审核 staging | | 做业务校验 | `ScheduledBriefService.ingestFromMcp(...)` 及 brief contract | 拒绝错误 taskName、超限请求、非法 JSON 和不符合约束的数据 | | 做幂等保护 | 以 `runId` 去重 | Scheduled 重试时不重复入库 | | 限制副作用 | 不发布、不自动审核、不创建 Gold、不删除历史 | 保持 External Teacher 只能进入人工审核闭环 | | 返回结构化结果 | accepted / duplicate / 安全错误的 output schema | 让 Scheduled 能保存真实的 `ingestId`、状态和失败原因 | | 提供测试和诊断 | 覆盖 `initialize`、`tools/list`、`tools/call`，并检查 Tunnel `readyz` | 区分工具未注册、后端未启动、Tunnel 未连接和 App metadata 缓存问题 | 本项目的关键代码位置： ```text apps/backend/src/modules/external-teacher/scheduled-brief-mcp.controller.ts apps/backend/src/modules/external-teacher/scheduled-brief-mcp.server.ts apps/backend/src/modules/external-teacher/scheduled-brief.service.ts apps/backend/src/modules/external-teacher/scheduled-brief.contract.ts apps/backend/src/modules/external-teacher/scheduled-brief-mcp.server.spec.ts ``` 安全边界也要分清：当前 Canary 的 MCP 工具声明为 `noauth`，但本地 MCP 地址不能直接暴露到公网；外部访问必须经过已经认证的 Secure MCP Tunnel。生产化时还要重新评估认证、部署常驻性、密钥轮换、限流和审计日志。 ## 2. 本项目当前固定值 | 项目 | 当前值 | | --- | --- | | 仓库目录 | `/Users/ronnie/Documents/my-project/maquanyifenzhong/maquanyifenzhong` | | Docker Compose project | `maquan-mcp-canary` | | 环境文件 | `.env.dev` | | 本地 MCP URL | `http://127.0.0.1:3000/api/v1/external-teacher/mcp` | | Tunnel profile | `maquan-local` | | Tunnel 健康页 | `http://127.0.0.1:8080/readyz` | | ChatGPT App 名 | `码圈一分钟·入库测试` | | brief 内固定 taskName | `码圈一分钟·程序员分时情报` | | 正式提示词 | `apps/deepseek-web-teacher-collector/prompts/chatgpt-scheduled-maquan-brief-v1-setup.txt` | `tunnel_id` 和 Runtime API Key 不写进这份可分享文档。`tunnel_id` 可以从 Platform Tunnel 页面或本机 profile 查看；API Key 不得发到聊天、截图、Git、Scheduled Prompt 或他人教程中。 ## 3. 费用边界 ChatGPT Pro 与 OpenAI API Platform 是两套独立计费系统。 本手册这条链路没有调用 Responses API、Chat Completions API 等模型 API： ```text ChatGPT Scheduled 负责推理和搜索 Runtime API Key 只用于 tunnel-client 连接 Tunnel 控制面 MCP 工具调用进入自己的 NestJS 和 MySQL ``` 因此看到“API 余额为 0”或“Go to Billing”的通用弹窗时，不需要为了本地 Tunnel Canary 立即充值。只有以后改成 `NestJS Cron + OpenAI Responses API` 时，才需要单独购买 API credits。 不要因为新增 MCP 工具而重新创建 API Key。只有 Key 泄漏、遗失、被撤销或组织权限变化时才轮换。 ## 4. 第一次准备本地后端 ### 4.1 打开 Docker Desktop 等待 Docker 状态变成 Running，然后执行： ```bash docker info >/dev/null && echo "Docker ready" ``` 必须看到： ```text Docker ready ``` ### 4.2 准备 `.env.dev` 首次运行： ```bash cd /Users/ronnie/Documents/my-project/maquanyifenzhong/maquanyifenzhong cp .env.prod.example .env.dev chmod 600 .env.dev ``` `.env.dev` 已被 `.gitignore` 忽略，不要强制提交。 至少确认： ```dotenv PORT=3000 NODE_ENV=development EXTERNAL_TEACHER_MCP_ENABLED=1 EXTERNAL_TEACHER_MCP_ALLOW_NO_AUTH=1 EXTERNAL_TEACHER_MCP_BEARER_TOKEN= EXTERNAL_TEACHER_MCP_MAX_BRIEF_BYTES=90000 RUN_MIGRATIONS=false ``` 数据库、Redis、RabbitMQ、JWT 和管理员密码使用仅供本地开发的随机值。`ALLOW_NO_AUTH=1` 只允许用于 OpenAI Secure MCP Tunnel Canary；不要把这个端点直接暴露到公网。 ### 4.3 启动依赖和后端 ```bash cd /Users/ronnie/Documents/my-project/maquanyifenzhong/maquanyifenzhong docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ up -d db redis rabbitmq qdrant model-api docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ up -d backend ``` 检查： ```bash docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ ps ``` 数据库、Redis、RabbitMQ 和 model-api 应为 healthy，backend 应为 Up。 ### 4.4 首次建立审核表 迁移脚本是幂等的，可以重复执行： ```bash docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ exec -T db sh -lc \ 'mysql -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE"' \ < database/migrations/manual-20260713-add-scheduled-brief-review.sql ``` 验证： ```bash docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ exec -T db sh -lc \ 'mysql -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE" -e \ "SHOW TABLES LIKE '\''scheduled_brief_%'\'';"' ``` 预期三个表： ```text scheduled_brief_ingests scheduled_brief_candidates scheduled_brief_quarantines ``` ### 4.5 检查本地 MCP 路由 ```bash curl -i http://127.0.0.1:3000/api/v1/external-teacher/mcp ``` 预期是 `405 Method Not Allowed`。这是正确结果：说明 MCP 路由存在，但 GET 不是协议调用方式。 常见异常： - `404`：`EXTERNAL_TEACHER_MCP_ENABLED` 没有生效； - `401`：当前配置要求 Bearer Token； - 连接失败：backend 没启动或 3000 端口不可达； - `500`：查看 backend 日志。 查看日志： ```bash docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ logs --tail=160 backend ``` ## 5. 第一次创建 Secure MCP Tunnel 如果 Tunnel 已经存在，整个第 5 节跳过，直接进入第 6 节。 ### 5.1 创建 Tunnel 打开： - Platform Tunnel settings： 操作： 1. 选择与 ChatGPT 登录对应的 organization； 2. 创建 Tunnel，例如命名 `maquan-local-canary`； 3. 关联实际使用 Scheduled 的 workspace； 4. 保存页面给出的 `tunnel_id`； 5. 按 Tunnel 页面入口创建一把专用 Runtime API Key。 个人 Canary 可以使用个人拥有的专用 Key。不要复用生产系统 Key，也不要把 Key 写进项目 `.env.dev`、提示词或 Git。 ### 5.2 安装 `tunnel-client` 优先使用 Platform Tunnel 页面提供的下载方式。安装后验证： ```bash tunnel-client --version tunnel-client help quickstart ``` ### 5.3 初始化本机 profile 如果需要临时输入 Runtime API Key： ```bash read -s "CONTROL_PLANE_API_KEY?粘贴 Runtime API Key（不会显示）: " export CONTROL_PLANE_API_KEY echo ``` 初始化： ```bash tunnel-client init \ --profile maquan-local \ --tunnel-id '<你的 tunnel_id>' \ --mcp-server-url 'http://127.0.0.1:3000/api/v1/external-teacher/mcp' ``` 本机 profile 位于： ```text ~/.config/tunnel-client/maquan-local.yaml ``` 它可能保存 Runtime API Key，因此必须： ```bash chmod 600 ~/.config/tunnel-client/maquan-local.yaml ``` 不要上传、转发或截图该文件。 ## 6. 每次启动 Tunnel 先确保 Docker backend 已经启动并且本地 GET 返回 405。 诊断： ```bash tunnel-client doctor --profile maquan-local --explain ``` 关键检查应当通过： ```text profile_load tunnel_id control_plane_api_key mcp_target mcp_server_reachable health_listener ``` 然后运行： ```bash tunnel-client run --profile maquan-local ``` 这个终端窗口需要保持运行。另开终端检查： ```bash curl -fsS http://127.0.0.1:8080/readyz ``` 预期： ```text ready ``` 如果希望 Mac 调试期间不要休眠，可另开终端： ```bash caffeinate -dimsu ``` 结束时按 `Ctrl+C`。 ## 7. 第一次创建 ChatGPT Developer Mode App ### 7.1 打开 Developer Mode 在 ChatGPT 设置中打开 Developer Mode，然后进入： - ### 7.2 创建 App 点击右上角 `+`： ```text Name：码圈一分钟·入库测试 Description：把码圈一分钟 Scheduled 生成的完整 JSON 提交到人工审核队列；不得发布、审核、删除或创建 Gold。 Connection：Tunnel Tunnel：选择 maquan-local-canary 或对应的 tunnel_id ``` 这条 Canary 不选择 OAuth 或 Mixed Auth。Runtime API Key 由 `tunnel-client` 使用，不填进 ChatGPT App 表单。 创建成功后，App 详情应显示： ```text get_maquan_connection_status submit_maquan_scheduled_brief_for_review ``` App 列表卡片仍只显示： ```text 码圈一分钟·入库测试 ``` 这是正常现象。 ### 7.3 Permissions 选择 在 App 的 Permissions 页面保持默认： ```text Allow low-risk actions ``` 不要选择： - `Always ask`：所有读取和写入都询问，会破坏 Scheduled 无人值守； - `Allow read actions`：只读连接检查可以自动执行，但正式 staging 入库仍会要求人工确认； - `Allow all actions`：权限过宽，本项目不需要承担该 elevated risk。 `Allow low-risk actions` 仍保留 ChatGPT 的安全判断：系统可以自动批准低风险动作，也可以拒绝涉及敏感信息的动作。当前写工具已声明 `readOnlyHint=false / destructiveHint=false / idempotentHint=true / openWorldHint=false`，且只能写入私有人工审核 staging，因此这是本项目调试和后续 Scheduled 运行的合适选择。 该设置不能替代真实 Canary；如果计划运行仍停在确认界面，应按“不具备当前无人值守权限”处理，而不是改成 `Allow all actions` 绕过。 ## 8. MCP 工具变化后怎样刷新 App 只要修改了工具列表、工具名称、描述、输入输出 schema 或 annotations，都要执行： 1. 重新构建或重启 NestJS backend； 2. 确认本地 MCP 路由返回 405； 3. 确认 Tunnel `/readyz` 返回 `ready`； 4. 打开 ； 5. 点击“码圈一分钟·入库测试”卡片或右侧 `...` 进入详情； 6. 点击 `Refresh`； 7. 核对工具列表。 这是 OpenAI 官方推荐的 Developer Mode App metadata 刷新流程。 只改 TypeScript MCP 代码时可执行： ```bash docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ restart backend ``` 如果修改了依赖、Dockerfile 或镜像内容，则执行： ```bash docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ up -d --build backend ``` 等本地 MCP GET 再次返回 405 后，才去 ChatGPT 点击 Refresh。 如果没有 `Refresh`，或者刷新后仍只显示旧工具： 1. 只删除 ChatGPT 中的“码圈一分钟·入库测试”App； 2. 不删除 Tunnel； 3. 不删除 Runtime API Key； 4. 不重新运行 `tunnel-client init`； 5. 点击 `+`，使用同一个 Tunnel 重建同名 App； 6. 再检查两个工具。 除非 Key 泄漏或 Tunnel 本身损坏，否则不要从 Platform 层重新开始。 ## 9. 创建 Scheduled 任务前的连接检查 最新正式提示词已允许创建阶段调用： ```text get_maquan_connection_status ``` 正确返回： ```json { "schemaVersion": "maquan-connection-status-v1", "status": "ready", "service": "maquan-scheduled-brief-review-ingest", "acceptedBriefSchema": "maquan-scheduled-brief-v1", "writeTool": "submit_maquan_scheduled_brief_for_review", "storageWritePerformed": false, "requiresHumanReview": true, "published": false, "goldCreated": false } ``` 创建阶段禁止调用写工具。只有 Scheduled 真正到点、搜索和 JSON 校验完成后，才调用： ```text submit_maquan_scheduled_brief_for_review ``` ## 10. 调试任务怎么安排 ### 10.1 先做一次性 Canary 不要一开始启用每天五次。先选一个距离当前至少 20 分钟的时间，创建一次性任务。 使用完整提示词： ```text apps/deepseek-web-teacher-collector/prompts/chatgpt-scheduled-maquan-brief-v1-setup.txt ``` 在完整提示词末尾追加创建方式覆盖，例如： ```text 【本次调试创建方式覆盖】 本次不要创建长期循环任务，只创建一个全新、独立、启用的一次性任务。 任务名称：码圈一分钟·真实内容Canary- 执行时间： 时区：Asia/Shanghai 只执行一次，不立即执行，不修改任何现有正式任务。 创建前只允许调用一次 get_maquan_connection_status。 只有 status=ready 且 storageWritePerformed=false 才能创建。 创建阶段禁止调用 submit_maquan_scheduled_brief_for_review。 任务到点后，按完整提示词搜索、核验、生成 JSON；最终校验通过后只调用一次 submit_maquan_scheduled_brief_for_review。 ``` 非正式时点还要明确使用真实时点生成 `scheduledAt` 和 `runId`，不要占用未来正式时点的 runId。 ### 10.2 连续调试频率 当前账号实测不接受同一任务每半小时运行。官方支持自定义 RRULE，但没有承诺本账号的最小间隔。 推荐： ```text 一次性 Canary → 成功后临时每小时一次 → 连续三个不同计划时点成功 → 删除调试任务 → 创建正式每天五次任务 ``` 临时每小时示例： ```text RRULE:FREQ=HOURLY;BYMINUTE=40 ``` 不要用两个任务错开半小时模拟半小时频率，否则会增加窗口重叠、重复检索、runId 和停用管理风险。 ## 11. 正式任务配置 连续三次真实内容 Canary 通过后，再创建唯一正式任务： ```text 任务名称：码圈一分钟·程序员分时情报 时区：Asia/Shanghai 执行时间：每天 05:40、11:40、17:40、20:40、23:40 RRULE:FREQ=DAILY;BYHOUR=5,11,17,20,23;BYMINUTE=40 ``` 完整创建提示词仍使用： ```text apps/deepseek-web-teacher-collector/prompts/chatgpt-scheduled-maquan-brief-v1-setup.txt ``` 同一正式时点只能有一个启用中的任务，避免两个任务生成相同 `runId`。 ## 12. 如何验收入库结果 ### 12.1 Scheduled 页面 检查： - 是否按时启动； - 是否完成而不是等待 Connect； - 是否保留一个合法 JSON 代码块； - 是否出现 `mcp_sync_failed:*` warning； - 是否没有发布或 Gold 相关动作。 ### 12.2 数据库 查看最近运行： ```bash docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ exec -T db sh -lc \ 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE" -e \ "SELECT run_id, item_count, featured_count, extended_count, review_status, ingested_at FROM scheduled_brief_ingests ORDER BY id DESC LIMIT 10;"' ``` 正确状态通常是： ```text review_status = pending_human_review ``` 它不应自动变成 approved，也不应直接进入 Gold。 查看隔离错误： ```bash docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ exec -T db sh -lc \ 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE" -e \ "SELECT run_id, error_code, error_message, created_at FROM scheduled_brief_quarantines ORDER BY id DESC LIMIT 10;"' ``` ## 13. 常见报错速查 | 现象 | 含义 | 处理 | | --- | --- | --- | | API 余额为 0 / Go to Billing | Platform 的通用计费提示 | 当前 Tunnel Canary 不调用模型 API，先关闭；不要重建 Key | | `Error fetching OAuth configuration` | 选成了 OAuth / Mixed Auth | 使用 Tunnel Connection，不选择 OAuth | | `Error creating connector` | backend、Tunnel、workspace 关联或缓存异常 | 先检查 405、`doctor`、`readyz`，再 Refresh / 重建 App | | App 只有写工具 | ChatGPT 仍缓存旧 metadata | 进入 App 详情点 Refresh；无 Refresh 才删除并用同一 Tunnel 重建 | | Scheduled 要只读连接检查 | App 只有写工具或 metadata 未刷新 | 确认存在 `get_maquan_connection_status` | | `502` | Tunnel 到本地 backend 失败 | 恢复 Docker/backend/Tunnel，不修改 runId 自动重试 | | `brief.taskName is not allowed` | brief 中 taskName 不符合白名单 | 必须固定为 `码圈一分钟·程序员分时情报` | | `PAYLOAD_TOO_LARGE` | JSON 超过服务端限制 | 保持提示词目标 80KB，服务端硬上限默认 90KB | | `RUN_ID_CONFLICT` | 同一 runId 对应了不同内容 | 检查是否有重复任务；不要修改 runId 逃避幂等 | | `status=duplicate` | 相同 runId、相同载荷已经入库 | 这是成功，不要再次提交 | | 任务停在 Connect | 当前账号/策略要求授权或 App 失去连接 | 先刷新 App；若持续需要人工确认，则不适合无人值守 | ## 14. 日常启动清单 以后重新开机，只需： 1. 打开 Docker Desktop； 2. 在仓库目录执行 Compose `up -d`； 3. `curl` 本地 MCP，确认 405； 4. `tunnel-client doctor --profile maquan-local --explain`； 5. `tunnel-client run --profile maquan-local` 并保持终端运行； 6. 检查 `curl http://127.0.0.1:8080/readyz` 返回 `ready`； 7. 不需要每天重建 App、Tunnel 或 API Key； 8. 只有 MCP metadata 改变时才在 ChatGPT 中 Refresh App。 ## 15. 停止和回滚 停止 Tunnel：在运行 `tunnel-client run` 的终端按 `Ctrl+C`。 停止本地容器但保留数据： ```bash docker compose \ --env-file .env.dev \ -p maquan-mcp-canary \ -f docker-compose.dev.yaml \ stop ``` 不要使用 `down -v`，否则会删除本地数据库 volume。 关闭 MCP 接入但保留其他服务： ```dotenv EXTERNAL_TEACHER_MCP_ENABLED=0 EXTERNAL_TEACHER_MCP_ALLOW_NO_AUTH=0 ``` 修改后重建或重启 backend。已入库 staging、审核记录和 Gold 不会因此删除。 ## 16. 安全规则 - Runtime API Key 不发聊天、不截图、不进 Git； - `~/.config/tunnel-client/maquan-local.yaml` 和 `.env.dev` 权限设为 `600`； - 不把 `ALLOW_NO_AUTH=1` 的 MCP 直接暴露公网； - MCP 只保留一个只读探针和一个受限 staging 写工具； - 不增加发布、删除、自动审核、覆盖历史或自动创建 Gold 的工具； - 每个 `runId` 最多主动提交一次； - 失败不修改 `runId` 自动重试； - 正式运行前把接收端迁移到常在线服务器，本地 Mac + 前台 Tunnel 只作为 Canary。 ## 17. 一分钟讲给别人听 可以这样解释： > 我们不是用 OpenAI API 调模型，而是让 ChatGPT Scheduled 自己完成搜索和结构化。ChatGPT 通过一个 Developer Mode App 发现我们的两个 MCP 工具：一个只读检查连接，一个把完整 JSON 放入人工审核 staging。Secure MCP Tunnel 负责把 ChatGPT 安全地连到本地 NestJS，不需要公开本地服务器。Runtime API Key 只给 Tunnel 客户端用，不是工具，也不应该写进提示词。后端按 runId 幂等、校验 JSON，并强制所有内容先人工审核，不能自动发布或创建 Gold。 ## 18. 官方参考 - [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) - [Apps SDK Quickstart：构建 MCP Server 并注册工具](https://developers.openai.com/apps-sdk/quickstart#build-an-mcp-server) - [创建 ChatGPT Developer Mode App](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt#create-a-developer-mode-app) - [刷新 Developer Mode App metadata](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt#refreshing-metadata) - [MCP 工具 annotations](https://learn.chatgpt.com/docs/submit-plugins#domain-verification) - [Scheduled 自定义 RRULE](https://learn.chatgpt.com/docs/automations#manage-scheduled-tasks) - [ChatGPT 与 API 分开计费](https://help.openai.com/en/articles/9039756-managing-billing-settings-on-chatgpt-web-and-platform) - [API prepaid billing](https://help.openai.com/en/articles/8264644-how-can-i-set-up-prepaid-billing) 项目实现和 Canary 退出条件详见：`docs/integrations/chatgpt-scheduled-mcp-canary-guide.md`。 ]]> http://herong.info/posts/AI-协作与边界/Codex 切换账号后项目和会话消失？一次完整的本地数据恢复实战 http://herong.info/posts/AI-协作与边界/Codex 切换账号后项目和会话消失？一次完整的本地数据恢复实战 Sun, 26 Jul 2026 16:30:00 GMT ## 完成本文后，你能解决什么 你将能够： - 判断丢失的是代码、会话文件，还是 Codex 的项目目录； - 区分代理、账号认证和本地工作区数据，避免把三者混为一谈； - 从 `$HOME/.codex` 或旧备份中找到项目快照； - 在不覆盖新会话的情况下，合并旧项目和会话归属； - 解释为什么“应用运行时写回状态”看似成功，重启后却又失败； - 建立一套切换账号、重装应用和清理代理前的备份流程。 本文以 macOS 上的 ChatGPT/Codex 桌面版为例。内部文件名可能随版本变化，因此先备份、再验证，永远比直接覆盖更重要。 ## 先理解：账号、代理和本地历史不是同一层 可以把 Codex 的数据分成三层： ```text 代码仓库 -> Git 仓库、源码、未提交修改 Codex 本地状态 -> 项目列表、会话索引、会话正文、项目与会话的归属关系 账号与网络 -> ChatGPT 登录、授权令牌、服务器代理、云端能力 ``` 服务器代理改变的是网络请求经过哪里，账号切换改变的是当前认证身份。它们不会自动把一台电脑上的本地项目目录迁移到另一个账户，也不应被当成备份方案。 OpenAI 官方文档说明，Codex 的 **Local** 和 **Worktree** 会话运行在用户电脑上；桌面端的本地 Work 会话也保留在本机，而 Codex 有独立的开发工作流历史。这意味着：切换账号后界面历史发生变化时，应同时检查本地状态，而不是立刻认定数据已在云端被删除。 - [Codex environments：Local 与 Worktree 在本机运行](https://learn.chatgpt.com/docs/environments/modes) - [桌面端本地会话与 Codex 独立历史](https://learn.chatgpt.com/docs/whats-new#keep-work-conversations-and-projects-together-on-desktop) > 本文后续涉及的 `$HOME/.codex` 文件结构来自一次真实故障恢复，不是稳定公开 API。不同版本可能使用不同文件名或数据库结构。 ## 第一步：停止删除，做完整备份 不要先重装，不要清空缓存，不要把旧 `.codex` 整目录覆盖到新目录。 先打开独立的“终端”应用，执行： ```bash backup_dir="$HOME/codex-backup-$(date +%Y%m%d-%H%M%S)" mkdir -p "$backup_dir" cp -a "$HOME/.codex" "$backup_dir/.codex" echo "备份位置：$backup_dir" ``` 如果桌面上已经有旧的 `.codex` 备份，也保留原样： ```bash cp -a "$HOME/Desktop/.codex" "$backup_dir/desktop-codex" ``` 如果实际目录叫 `.codex-before-restore-日期`，把命令中的源路径替换成真实名称。 ### 不要分享这些文件 `.codex` 可能包含认证信息、配置、对话正文、代码路径和工具日志。特别注意： - 不要把 `auth.json` 发给别人； - 不要把整个 `.codex` 上传到公开网盘或 Git 仓库； - 不要为了恢复项目，把旧账户的认证文件复制给新账户； - 教程截图中应隐藏用户名、邮箱、绝对路径和会话内容。 ## 第二步：确认代码仓库还在 项目列表消失，不代表项目目录被删除。先检查常用代码目录： ```bash find "$HOME/Documents" -maxdepth 4 -type d -name .git -print 2>/dev/null ``` 如果仓库仍在，Git 状态也正常： ```bash git -C "$HOME/path/to/project" status ``` 那么代码层基本安全，接下来恢复的是 Codex 的目录和会话关系。 ## 第三步：盘点会话与项目快照 常见的关键数据包括： ```text $HOME/.codex/.codex-global-state.json $HOME/.codex/.codex-global-state.json.bak $HOME/.codex/..codex-global-state.json.tmp-* $HOME/.codex/session_index.jsonl $HOME/.codex/sessions/ $HOME/.codex/archived_sessions/ $HOME/.codex/logs_*.sqlite $HOME/.codex/state_*.sqlite ``` 其中： - `session_index.jsonl` 可用于判断历史会话索引是否还在； - `sessions/` 和 `archived_sessions/` 可能保存会话记录； - `.codex-global-state.json` 保存桌面端当前项目目录等状态； - 临时的 `..codex-global-state.json.tmp-*` 有时保留着故障前的完整项目列表； - SQLite 文件可能包含更多运行和索引状态，但不建议在不了解表结构时直接修改。 先统计会话索引： ```bash wc -l "$HOME/.codex/session_index.jsonl" find "$HOME/.codex/sessions" "$HOME/.codex/archived_sessions" \ -type f -name '*.jsonl' 2>/dev/null | wc -l ``` 再查看有哪些全局状态快照： ```bash find "$HOME/.codex" -maxdepth 1 -type f \ \( -name '*global-state*' -o -name '*.bak' \) -print ``` 故障案例中，当前状态只有 1 个项目，但旧临时快照包含 19 个项目和 122 条历史会话归属；会话索引本身有 821 条。这说明“会话还在，项目目录丢了”。 ## 第四步：先预览，不要直接写回 下载或保存本文附带的 `recover-codex-projects.mjs`，然后在终端中运行预览： ```bash node recover-codex-projects.mjs \ --codex-home "$HOME/.codex" ``` 如果旧快照位于另一个备份目录： ```bash node recover-codex-projects.mjs \ --codex-home "$HOME/.codex" \ --source-dir "$HOME/Desktop/.codex-before-restore" ``` 没有全局 Node.js 时，可以使用 ChatGPT 桌面应用自带的 Node： ```bash node_bin="/Applications/ChatGPT.app/Contents/Resources/cua_node/bin/node" "$node_bin" recover-codex-projects.mjs \ --codex-home "$HOME/.codex" \ --source-dir "$HOME/Desktop/.codex-before-restore" ``` 预览输出应包含： ```json { "applied": false, "before": { "projects": 1, "assignments": 4 }, "after": { "projects": 19, "assignments": 126 } } ``` 重点检查： - `sourceSnapshot` 是否真的是旧快照； - `after.projects` 是否符合记忆； - `projects[].rootPath` 是否指向真实目录； - `directoryExists` 为 `false` 的项目是否确实已经移动或删除。 ## 第五步：完全退出应用，再执行恢复 这是整个恢复流程最容易失败的地方。 如果在 ChatGPT/Codex 仍运行时修改 `.codex-global-state.json`，文件可能暂时显示恢复成功；但应用退出时会把内存中的旧状态重新写回磁盘，于是重启后仍只看到一个项目。 正确顺序： 1. 保持独立的“终端”应用打开； 2. 在 ChatGPT/Codex 中按 `Command + Q` 完全退出； 3. 确认主进程已经消失； 4. 从终端执行恢复； 5. 验证文件后再重新打开应用。 确认进程： ```bash pgrep -x ChatGPT || echo "ChatGPT 已退出" pgrep -x Codex || echo "Codex 已退出" ``` 执行恢复： ```bash node recover-codex-projects.mjs \ --codex-home "$HOME/.codex" \ --source-dir "$HOME/Desktop/.codex-before-restore" \ --apply ``` 脚本会： - 选择项目数量最多、会话归属最完整的状态快照； - 按项目根目录去重； - 保留当前新项目和新会话； - 修正同一路径对应的新旧项目 ID； - 合并历史会话的项目归属； - 写入前备份当前状态； - 使用临时文件加原子重命名，降低半写入风险； - 同步更新 `.codex-global-state.json.bak`。 备份默认写入： ```text $HOME/codex-recovery-backups/<时间戳>/ ``` 验证成功后重新打开： ```bash open -a ChatGPT ``` ## 为什么直接覆盖整个 `.codex` 很危险 旧目录中可能同时包含： - 过期登录凭据； - 旧版配置格式； - 当前账号不再适用的插件或 MCP 配置； - 较旧的数据库； - 新会话不存在于旧备份中的状态。 整目录覆盖可能把“项目丢失”升级成“认证、插件、数据库和新会话一起损坏”。 更安全的恢复范围是： ```text 旧项目目录 + 旧项目顺序 + 历史会话归属 + 当前新项目和新会话 = 合并后的全局状态 ``` 不要迁移： ```text 旧 auth.json 旧账户令牌 来源不明的 config.toml 未经验证的 SQLite 整库 ``` ## 如果让 Codex 自己修复，为什么普通后台脚本也会失败 本次恢复中还踩到了第二个坑：Codex 自己启动了一个 `nohup` 后台脚本，计划等应用退出后再写回状态。但 ChatGPT/Codex 退出时，它的子进程也被清理，脚本没有机会继续执行。 因此有两种可靠方式： ### 推荐：在独立终端手动执行 这是最简单、最透明的方法。应用退出后，终端仍然存在，可以直接执行恢复命令。 ### 自动化：交给 macOS `launchd` `launchd` 由操作系统管理，不依赖 ChatGPT/Codex 进程。适合必须由自动化程序完成“等待退出 -> 写回 -> 验证 -> 重启”的场景。 执行前必须验证： ```bash launchctl print "gui/$(id -u)/你的任务标签" ``` 应看到： ```text state = running active count = 1 ``` 仅看到任务已提交不够；还要检查独立日志，避免任务因为找不到 `node` 而以退出码 `127` 失败。`launchd` 环境的 `PATH` 很短，脚本内应使用 Node、`open`、`date` 等命令的绝对路径。 对于普通读者，没有必要先上 `launchd`。独立终端方案足够可靠。 ## 服务器代理和账号切换前的正确做法 以后准备切换代理、组织账号或个人账号时，先完成下面的检查： ### 1. 保存代码 ```bash git -C "$HOME/path/to/project" status git -C "$HOME/path/to/project" diff ``` 未提交修改至少复制到独立备份，不要假设 Codex 会话能替代 Git。 ### 2. 备份 Codex 本地状态 ```bash backup_dir="$HOME/codex-backup-$(date +%Y%m%d-%H%M%S)" mkdir -p "$backup_dir" cp -a "$HOME/.codex" "$backup_dir/.codex" ``` 备份应离线保存并限制访问权限。 ### 3. 记录项目清单 ```bash find "$HOME/Documents" -maxdepth 4 -type d -name .git -print \ > "$backup_dir/git-projects.txt" ``` ### 4. 只清理明确目标 如果只是更换代理，不要顺手删除： ```text $HOME/.codex/sessions/ $HOME/.codex/archived_sessions/ $HOME/.codex/session_index.jsonl $HOME/.codex/*global-state* $HOME/.codex/*.sqlite ``` 如果只是退出账号，也不要把“清凭据”和“删历史”混成一个操作。 ### 5. 切换后立刻做最小验证 - 原项目是否还在列表； - 最近会话能否搜索； - 新建一个测试项目后，重启是否仍存在； - `$HOME/.codex` 中的索引文件是否还在增长； - 代理关闭后，登录和本地项目是否仍可分别工作。 ## 故障判断速查表 | 现象 | 更可能的问题 | 首选检查 | |---|---|---| | 项目列表消失，但代码目录还在 | 项目目录状态丢失 | `*global-state*` 快照 | | 项目还在，会话标题不见 | 会话索引缺失 | `session_index.jsonl` | | 索引有很多行，界面仍为空 | 当前状态未挂回项目或应用未重新加载 | 会话归属、完全退出重开 | | 修改文件后立刻恢复，重启又丢 | 运行中的应用在退出时覆盖文件 | 退出后写回 | | 旧目录有记录，新目录没有 | 清理、重装或账户切换期间换了状态目录 | 对比两个 `.codex` | | 代理可用但历史没回来 | 网络恢复不等于本地状态恢复 | 检查本机文件 | | 仓库目录真的不存在 | 代码层丢失 | Git 远端、Time Machine、磁盘备份 | ## 回滚方法 如果恢复后项目显示异常，先完全退出应用，再回滚刚才的备份： ```bash cp "$HOME/codex-recovery-backups/<时间戳>/.codex-global-state.before-restore.json" \ "$HOME/.codex/.codex-global-state.json" cp "$HOME/.codex/.codex-global-state.json" \ "$HOME/.codex/.codex-global-state.json.bak" ``` 然后重新打开 ChatGPT。 不要删除恢复目录，直到确认： - 项目数量正确； - 每个项目路径正确； - 历史会话能打开； - 新建会话后重启仍然存在； - 当前个人账号登录和插件配置正常。 ## 最终结论 遇到“切换账号后 Codex 项目和会话消失”，先不要把它理解成云端永久删除。 按照下面的顺序排查： ```text 代码目录是否存在 -> 会话文件是否存在 -> 会话索引是否存在 -> 旧项目快照是否存在 -> 合并旧项目与当前新状态 -> 完全退出应用 -> 写回、验证、重启 ``` 最重要的经验有三条： 1. 账号认证、服务器代理和本地历史是三套不同问题； 2. 恢复时只合并必要状态，不整目录覆盖； 3. 修改 Codex 状态必须在应用完全退出后完成。 只要代码目录、会话文件或旧状态快照仍在，项目列表消失通常还有恢复空间。真正决定恢复成功率的，不是重装次数，而是是否及时停止删除、保存原始证据，并在写回前理解哪一层数据出了问题。 ]]> http://herong.info/posts/AI-协作与边界/使用 AI Agent 接管项目开发的工程化思路 http://herong.info/posts/AI-协作与边界/使用 AI Agent 接管项目开发的工程化思路 Tue, 12 May 2026 00:00:00 GMT AI 能读懂、能修改、能验证、能回滚的工程系统。 所以整体思路是： ```txt 项目文档化 ↓ 需求模板化 ↓ 代码规范化 ↓ 验证自动化 ↓ 任务小步化 ↓ 经验沉淀化 ``` 也就是说，人主要负责： * 定方向 * 定业务规则 * 定验收标准 * Review AI 的结果 AI 主要负责： * 阅读上下文 * 拆解任务 * 修改代码 * 补测试 * 总结变更 自动化工具负责： * lint * typecheck * test * build * CI 检查 --- ## 二、第一步：整理项目入口文件 建议先补齐这些文件： ```txt project-root/ ├── README.md ├── AGENTS.md ├── CLAUDE.md ├── docs/ │ ├── 00-project-overview.md │ ├── 01-architecture.md │ ├── 02-code-style.md │ ├── 03-business-rules.md │ └── 07-agent-workflow.md ``` 其中： | 文件 | 作用 | | ---------------- | ----------------------- | | `README.md` | 给人看的项目入口 | | `AGENTS.md` | 给通用 AI Agent 看的项目规则 | | `CLAUDE.md` | 给 Claude Code 看的项目记忆 | | `docs/` | 存放项目结构、业务规则、接口、数据库、开发流程 | | `.cursor/rules/` | 给 Cursor 的项目规则 | --- ## 三、README.md 怎么写 `README.md` 不需要特别长，主要让人快速知道这个项目是什么、怎么跑、常用命令是什么。 ````md # 项目名称 ## 项目定位 这是一个什么项目，解决什么问题，目标用户是谁。 ## 技术栈 - Frontend: - Backend: - Database: - Cache: - Queue: - AI Provider: ## 本地启动 ```bash pnpm install pnpm dev ``` ## 常用命令 ```bash pnpm lint pnpm typecheck pnpm test pnpm build ``` ## 主要目录 * src/modules：业务模块 * src/common：公共能力 * docs：项目文档 ```` --- ## 四、AGENTS.md 怎么写 `AGENTS.md` 是给 AI Agent 看的核心规则文件。 它应该告诉 AI： - 这个项目是什么 - 修改代码前要先读哪些文档 - 不能做什么 - 修改后要怎么验证 - 输出格式有什么要求 最简示例： ````md # AGENTS.md ## Role 你是本项目的 AI 编程助手，负责辅助实现新功能、修复 bug、重构代码和补充测试。 ## Project Overview 修改代码前，请先阅读： - docs/00-project-overview.md - docs/01-architecture.md - docs/02-code-style.md - docs/03-business-rules.md ## Before Coding 在修改代码前，必须先完成： 1. 复述你理解的需求 2. 列出可能影响的文件 3. 给出修改方案 4. 标明风险点 ## Coding Rules - 不要无意义重构 - 不要扩大需求范围 - 不要引入未确认的新依赖 - 修改代码时优先保持现有架构 - 关键逻辑必须补充中文注释 - TypeScript 项目禁止使用 any - 后端接口必须考虑错误处理和边界条件 ## Verification 修改完成后，优先运行： ```bash pnpm lint pnpm typecheck pnpm test pnpm build ``` 如果无法运行，必须说明原因，并给出人工检查点。 ## Output Style 回答时优先给必要修改点，不要重复输出完整文件，除非用户明确要求。 ```` --- ## 五、CLAUDE.md 怎么写 如果你使用 Claude Code，可以单独准备 `CLAUDE.md`。 ```md # CLAUDE.md ## 项目协作方式 本项目使用 AI Agent 辅助开发，但所有改动必须保持小步、可验证、可回滚。 ## 用户偏好 - 默认使用中文交流 - 代码修改只给必要片段 - 不要重复输出完整代码 - 关键逻辑上一行加中文注释 - 优先给可执行方案，不要空泛解释 ## 开发原则 - 先读 docs，再改代码 - 先方案，后实现 - 先复用现有模块，不随意新建抽象 - 不为“看起来高级”而重构 - 不确定业务规则时，先标出假设 ## 必读文档 - docs/00-project-overview.md - docs/01-architecture.md - docs/03-business-rules.md - docs/07-agent-workflow.md ``` --- ## 六、docs 目录怎么设计 推荐先建这几个文档： ```txt docs/ ├── 00-project-overview.md ├── 01-architecture.md ├── 02-code-style.md ├── 03-business-rules.md ├── 04-api-design.md ├── 05-database.md ├── 06-testing.md ├── 07-agent-workflow.md └── adr/ ``` ### 1. 项目概览 ```md # 项目概览 ## 项目目标 这个项目要解决什么问题。 ## 核心用户 谁会使用这个系统。 ## 核心模块 - 用户模块 - 内容模块 - 采集模块 - AI 处理模块 - 后台管理模块 ## 当前阶段 当前优先级是什么，哪些功能先不做。 ``` ### 2. 架构说明 ```md # 架构说明 ## 技术栈 - Frontend: - Backend: - Database: - Cache: - Queue: - AI: ## 数据流 用户请求 → Controller → Service → Repository → Database AI 任务 → Job → Queue → Worker → Model API → Result Storage ## 模块边界 每个模块负责什么，不负责什么。 ``` ### 3. 代码规范 ```md # 代码规范 ## 命名规则 - 方法名使用完整可读名称，不使用无意义缩写 - 布尔值使用 is/has/can/should 开头 - 查询方法使用 find/get/list/search 区分语义 ## TypeScript 规则 - 禁止 any - DTO、Entity、Response 必须有明确类型 - 条件判断较多时，优先抽成具名函数 ## 注释规则 - 不解释显而易见的代码 - 只解释业务规则、边界条件和容易误解的逻辑 ``` ### 4. 业务规则 这个文件非常重要，因为 AI 最容易出错的地方通常不是语法，而是业务理解。 ```md # 业务规则 ## 内容生成规则 - 无来源则不写 - URL 必须来自可信来源 - AI 摘要不能虚构原文没有的信息 - 低可信来源只能作为补充阅读 ## 用户规则 - 普通用户可以查看公开内容 - 管理员可以管理内容 - 未登录用户不能访问后台接口 ## 排序规则 - 优先展示高质量内容 - 低质量内容降权 - 已读内容可以降低展示优先级 ``` --- ## 七、Agent 开发流程怎么写 建议单独建： ```txt docs/07-agent-workflow.md ``` 内容如下： ```md # Agent 开发流程 ## 新功能流程 1. 阅读相关 docs 2. 复述需求 3. 列出影响范围 4. 给出实现方案 5. 小步修改 6. 补充测试或验证方式 7. 总结改动 ## Bug 修复流程 1. 复现问题 2. 定位原因 3. 判断影响范围 4. 最小改动修复 5. 补充回归验证方式 ## 重构流程 1. 不改变外部行为 2. 先列出重构目标 3. 一次只重构一个方向 4. 保留兼容层 5. 必须给出验证方式 ``` --- ## 八、任务模板怎么准备 建议建目录： ```txt docs/tasks/ ├── feature-template.md ├── bugfix-template.md └── refactor-template.md ``` ### 新功能模板 ```md # Feature Request ## 背景 为什么要做这个功能。 ## 目标 这个功能最终要达到什么效果。 ## 用户路径 用户会怎么使用它。 ## 业务规则 - 规则 1 - 规则 2 - 规则 3 ## 非目标 这次明确不做什么。 ## 影响范围 - 前端： - 后端： - 数据库： - 定时任务： - AI 逻辑： ## 验收标准 - [ ] 能正常创建 - [ ] 能正常查询 - [ ] 异常情况有提示 - [ ] 权限校验正确 - [ ] 构建通过 ``` ### Bug 修复模板 ```md # Bug Report ## 问题现象 具体表现是什么。 ## 复现步骤 1. 2. 3. ## 期望结果 应该是什么样。 ## 实际结果 现在是什么样。 ## 相关文件 如果已知，列出来。 ## 修复要求 - 不扩大修改范围 - 优先最小改动 - 修复后说明根因 - 给出回归验证方式 ``` ### 重构模板 ```md # Refactor Request ## 当前问题 现在代码哪里不好。 ## 重构目标 希望改善什么。 ## 约束 - 不改变外部接口 - 不改变数据库结构 - 不影响现有功能 - 不引入新依赖 ## 验收标准 - [ ] 原功能正常 - [ ] 代码重复减少 - [ ] 模块边界更清晰 - [ ] 测试或构建通过 ``` --- ## 九、自动验证命令必须准备好 AI Agent 编程一定要有验证命令。 否则 AI 改得越快，风险越大。 `package.json` 建议补这些命令： ```json { "scripts": { "lint": "eslint .", "typecheck": "tsc --noEmit", "test": "vitest run", "build": "pnpm typecheck && vite build", "check": "pnpm lint && pnpm typecheck && pnpm test" } } ``` 然后要求 AI 每次修改后都说明： ```txt 已执行： - pnpm lint - pnpm typecheck - pnpm test 如果没有执行，需要说明原因。 ``` --- ## 十、Cursor 规则怎么放 如果你使用 Cursor，可以加： ```txt .cursor/ └── rules/ ├── project.mdc ├── backend.mdc ├── frontend.mdc └── testing.mdc ``` 例如： ```md --- description: Backend coding rules globs: - "backend/**/*.ts" alwaysApply: false --- # Backend Rules - 使用 NestJS 风格组织代码 - Service 负责业务逻辑 - Controller 只负责入参、出参和鉴权 - Entity 不写业务逻辑 - DTO 必须显式定义字段 - 不允许使用 any - 新增接口时需要同步补充错误处理 ``` --- ## 十一、以后怎么向 AI 提需求 不要直接说： ```txt 帮我做一个用户积分系统。 ``` 这种说法边界太大，AI 容易乱改。 建议这样说： ```md 我要新增“用户积分系统”。 请先不要写代码，先阅读： - AGENTS.md - CLAUDE.md - docs/00-project-overview.md - docs/01-architecture.md - docs/03-business-rules.md 然后输出： 1. 你理解的需求 2. 需要新增/修改的文件 3. 数据表设计 4. 接口设计 5. 前端页面影响 6. 风险点 7. 分阶段实现计划 确认方案后，再开始改代码。 ``` --- ## 十二、推荐落地顺序 ### 第 1 阶段：建立项目上下文 先补： ```txt README.md AGENTS.md CLAUDE.md docs/00-project-overview.md docs/01-architecture.md docs/02-code-style.md ``` 目标：让 AI 进入项目后不迷路。 --- ### 第 2 阶段：沉淀业务规则 再补： ```txt docs/03-business-rules.md docs/04-api-design.md docs/05-database.md ``` 目标：减少 AI 乱猜业务。 --- ### 第 3 阶段：建立任务模板 再补： ```txt docs/tasks/feature-template.md docs/tasks/bugfix-template.md docs/tasks/refactor-template.md ``` 目标：以后所有需求都能按模板输入。 --- ### 第 4 阶段：建立自动校验 补齐： ```txt pnpm lint pnpm typecheck pnpm test pnpm build pnpm check ``` 目标：AI 改完后可以快速验证。 --- ### 第 5 阶段：沉淀架构决策 新增： ```txt docs/adr/ ``` 每次重要技术选择写一篇 ADR： ```md # 0001-use-xxx ## 背景 为什么需要做这个选择。 ## 决策 最终选择什么。 ## 原因 为什么这样选。 ## 影响 带来什么好处和代价。 ``` 目标：避免以后 AI 不知道历史原因，反复推翻架构。 --- ## 十三、最终建议 如果你现在要开始落地，不要一上来写一大堆文档。 先建最小版本： ```txt README.md AGENTS.md CLAUDE.md docs/ ├── 00-project-overview.md ├── 01-architecture.md ├── 02-code-style.md ├── 03-business-rules.md └── 07-agent-workflow.md ``` 然后以后每次新需求都按这个格式： ```md 请按本项目 Agent 开发流程处理这个需求。 需求： xxx 要求： 1. 先不要直接改代码 2. 先阅读 AGENTS.md、CLAUDE.md 和 docs 目录 3. 复述你理解的需求 4. 列出影响文件 5. 给出实现方案 6. 等我确认后再开始修改 ``` 这样项目会慢慢变成一个 AI 友好的工程资产。 真正的 Agent 编程，不是让 AI 随便写代码，而是： > 把项目经验沉淀成 AI 可读取的上下文； > 把需求拆成 AI 可执行的小任务； > 把修改结果交给自动化验证； > 把每次踩坑反向更新成项目规则。 ]]> http://herong.info/posts/Electron/JS 如何通过 V8 与 C++ 绑定调用系统能力 http://herong.info/posts/Electron/JS 如何通过 V8 与 C++ 绑定调用系统能力 Tue, 19 May 2026 00:00:00 GMT **主进程里**：JavaScript 通过 V8 调用「启动时已注册的 C++ 函数」，间接使用操作系统能力。 > **渲染进程里（Vue）**：默认**不是**同一个 V8、也**不是**完整 Node；要碰系统得通过 **IPC** 找主进程。 下面按「先分清两套运行时 → 再理解主进程怎么过桥 → 最后看 Vue 怎么间接用能力」的顺序讲。 --- ## 一、最容易混的一点：不是同一个 Node，也不是同一个 V8 很多人以为 `main.cjs` 和 Vue 打包后的 JS「都在 Electron 里跑，应该是同一个引擎」。**其实不是。** ### 1.1 两套 JS，跑在两个进程里 ```text ┌──────────── 主进程 ────────────┐ ┌────────── 渲染进程 ──────────┐ │ electron/main.cjs │ │ Vue 打包后的 JS（dist） │ │ Node 运行时 ✅ │ │ Node 运行时 ❌（通常已关闭） │ │ require('electron') ✅ │ │ 更像 Chrome 里跑网页 │ │ require('fs') ✅ │ │ 只有 Web API + 可选 preload │ │ 自己的 V8 isolate │ │ 自己的 V8 isolate │ └────────────────────────────────┘ └────────────────────────────────┘ │ │ └──────────── IPC（跨进程消息）─────────────┘ ``` | 代码 | 跑在哪 | 环境 | |------|--------|------| | **`main.cjs`** | 主进程 | 完整 **Node + Electron** | | **Vue 业务代码** | `BrowserWindow` 里的渲染进程 | **Chromium**（接近浏览器） | 配置了 `nodeIntegration: false` 时，Vue 里**不能**像 `main.cjs` 那样随便 `require('fs')`。 ### 1.2 两个 V8 一样吗？——不一样 | | 主进程 | 渲染进程（Vue） | |---|--------|----------------| | 进程 | 1 个 Electron 主进程 | 每个窗口至少 1 个 Chromium 渲染进程 | | V8 | 给 **Node** 用的那份 | 给 **网页** 用的那份（在 Chromium 里） | | 是否同一个堆/上下文 | ❌ 隔离的 **两个（或多个）V8 isolate** | ❌ | 类比： - 主进程 V8 ≈ 后台服务里的 JS 引擎 - 渲染进程 V8 ≈ Chrome 打开一个标签页里的 JS 引擎 **不是「一个 V8 跑两份代码」**，而是 **两个进程各有一个 V8**。 `main.cjs` 的 JS 和 Vue 的 JS **不会**跟同一个 V8 实例交互。 ### 1.3 两个 Node 一样吗？——也不一样 更准确地说：**只有主进程那份算「在 Node 里」。** - **主进程**：Electron 内置 Node，跑 `main.cjs`。 - **渲染进程**（现代默认配置）：**没有**把完整 Node 暴露给 Vue；页面 JS 由 **Chromium** 执行，环境接近浏览器。 > Vue 里的 JS **不是**和 `main.cjs` 共用同一个 Node 进程里的 Node API。 ### 1.4 为什么都是 JavaScript，却感觉像「都在 Electron 里」？ 因为 **Electron 这个桌面应用** 同时带了： - 一套 **Node 主进程**（管窗口、文件、子进程） - 一套 **Chromium**（显示 Vue 页面） 对外是一个 App，对内是 **多进程**： ```text electron 可执行文件 ├── 主进程：Node + V8 + main.cjs └── 渲染进程：Chromium + V8 + Vue（无完整 Node） ``` `window.loadURL(...)` 的作用：主进程让 Chromium **另起一个渲染进程** 去加载你的页面。 ### 1.5 三个问题，一张表 | 问题 | 答案 | |------|------| | `main.cjs` 和 Vue 会跟**同一个 V8** 交互吗？ | **不会**，各进程各有一个 V8 | | Vue 的 JS 也在 **Node** 里跑吗？ | **默认不会**，在 Chromium 渲染进程里跑 | | 两个 Node 一样吗？ | **不一样**；实质是主进程有 Node，Vue 侧没有完整 Node | 后面说的「绑定好了，JS 一调就进 C++」——**对主进程的 `main.cjs` 成立**；**对 Vue 页面**，默认只有浏览器那套（DOM、`fetch` 等），要碰系统得 **IPC 找主进程**。 --- ## 二、主进程里：JS 怎么碰到系统 ### 2.1 调用链路（心智模型） **不是「JS 被编译成 C++ 指令」**，而是一次跨语言函数调用： ```text 你写的 JS（require('fs').readFile、new BrowserWindow()） ↓ V8 执行，遇到「原生绑定」（Native Binding） ↓ 跳进 Electron / Node 里用 C++ 写好的函数 ↓ C++ 调操作系统 API ↓ 结果包装成 JS 值，还给 V8 / 你的代码 ``` ```text ┌─────────────┐ 原生绑定层 ┌─────────────┐ 系统 API ┌──────────┐ │ 你的 JS │ ─────────────────→ │ C++ 实现 │ ──────────────→ │ 操作系统 │ │ (V8 执行) │ ←───────────────── │ (Node/Electron)│ ←────────────── │ │ └─────────────┘ 返回值转成 JS 值 └─────────────┘ └──────────┘ ``` | 层级 | 职责 | |------|------| | **V8** | 解析、执行 JavaScript | | **C++ 绑定层** | 注册「JS 函数 ↔ C++ 函数」的桥（`fs`、`BrowserWindow`…） | | **操作系统** | 真正的文件、窗口、进程、网络 | 记法：**运行时桥接**，不是 **编译期翻译**。 | 说法 | 对不对 | |------|--------| | 调 `readFile` 时跳到同进程里的 C++ 函数 | ✅ | | 整份业务 JS 先编译成 C++ 机器码再跑 | ❌ | ### 2.2 事先注册好的「插座」 C++ 绑定像 **开机时已装好的插座**： 1. **Electron / Node 启动时**，C++ 向 V8 **注册**原生函数（`fs.readFile`、`BrowserWindow`、`app.whenReady`…）。 2. JS 里它们看起来像普通对象、方法。 3. **一调用**，V8 **直接跳进**已注册的 C++，不会把整段业务 JS「翻译成 C++」。 4. C++ 完成后，把返回值变回 JS 类型。 > **绑定事先写好 → JS 一调 → 就等于执行那段 C++。**（**仅主进程**这条链路。） | | 自写 `function foo() {}` | `fs.readFile` 等原生 API | |--|--------------------------|---------------------------| | 谁执行 | V8 跑 JS | V8 转调已注册 C++ | | 能否碰系统 | 不能（除非再调别的 API） | 能 | | 要不要注册 | 不需要 | **必须** | **只有被注册过的 API 才能过桥**；自写函数不会自动变 C++。 ### 2.3 主进程示例 ```js // main.cjs（主进程） const { app, BrowserWindow } = require('electron') const fs = require('fs') app.whenReady().then(() => { const win = new BrowserWindow({ width: 800, height: 600 }) // new BrowserWindow() → C++ 绑定 → 系统创建窗口 }) ``` ```text main.cjs → 主进程 V8 → 命中 C++ 绑定 → 系统 API → 返回 JS 对象 ``` 全程在**主进程一个进程**内完成，对你来说就是「调了一个 JS 函数」。 --- ## 三、渲染进程里：Vue 怎么间接用系统能力 渲染进程里跑的是 **Chromium + Vue**。`nodeIntegration: false` 时： - 不能随意 `require('fs')`、不能 `new BrowserWindow()` - 页面 JS 由 **渲染进程自己的 V8** 执行，但**没有**主进程那排 Node/Electron「插座」 ### 3.1 标准路径：IPC 不能指望「和 main 共用同一个 V8/Node」，而是： ```text Vue（渲染进程 V8） → ipcRenderer.invoke('run-agent', ...) → 主进程 ipcMain（主进程 V8 + Node） → fs.readFile / child_process / BrowserWindow … → 结果经 IPC 回传 Vue ``` | 进程 | 能否直接走 C++ 绑定 | 典型方式 | |------|---------------------|----------| | 主进程 | ✅ | `require('electron')`、`fs` | | 渲染进程 | ❌（默认） | `preload` + `contextBridge` + **IPC** | **主进程**：同进程函数调用，直接插「插座」。 **渲染进程**：发消息，请主进程代插「插座」。 ### 3.2 preload：窄口子，不是第二套 Node **preload** 仍在渲染进程，在页面加载前执行，用 `contextBridge` 向页面暴露**白名单** API（如 `window.api.readFile`）。 ```text Vue 调用 window.api.readFile(path) → preload 里封装的 ipcRenderer.invoke → 主进程 fs.readFile（C++ 绑定 → 系统） ``` preload **不会**在渲染进程再注册一套 C++ 绑定；只是把 IPC 包成好用的 JS 函数。 --- ## 四、总览图 ```mermaid flowchart TB subgraph renderer [渲染进程：独立 V8，无完整 Node] Vue[Vue / 页面 JS] Preload[preload + contextBridge] Vue --> Preload end subgraph main [主进程：独立 V8 + Node] MainJS[main.cjs] Bindings[启动时注册的 C++ 绑定] MainJS --> Bindings end subgraph os [操作系统] SysAPI[文件 / 窗口 / 进程 API] end Preload -->|IPC| MainJS Bindings --> SysAPI SysAPI --> Bindings Bindings -->|JS 值| MainJS MainJS -->|IPC 结果| Preload ``` --- ## 五、自检清单 **进程与运行时** - [ ] 能说清主进程、渲染进程是**两个进程、两个 V8** - [ ] 知道 Vue 默认**不在**完整 Node 里跑 - [ ] 知道 `main.cjs` 与 Vue **不共用**同一个 V8 堆 **主进程与绑定** - [ ] 能说清 V8、C++ 绑定、系统 API 各管什么 - [ ] 知道绑定是**启动时注册**的「插座」，调用时跳进 C++ - [ ] 知道自写 `function` 不会变 C++；只有已注册 API 能过桥 - [ ] 不会把「JS 调系统」理解成「JS 编译成 C++」 **渲染进程与 IPC** - [ ] 知道渲染进程默认要靠 **IPC** 让主进程调系统 API - [ ] 知道 preload 是 IPC 的薄封装，不是第二套 Node --- ## 六、小结 | 维度 | 主进程（`main.cjs`） | 渲染进程（Vue） | |------|----------------------|-----------------| | V8 | 主进程里、给 Node 用 | Chromium 里、给网页用 | | Node | ✅ 完整 Node + Electron | ❌ 通常关闭 `nodeIntegration` | | 调系统 | JS → 已注册 C++ → 系统 API | IPC → 主进程再调 C++ | | 记忆 | 「插座」在主进程墙上 | 通过 IPC 请主进程插电 | 学 Electron 桌面端，建议顺序： 1. 先分清 **两套 V8 / 两套进程**（本章第一节） 2. 再理解主进程 **注册 + 跳转**（第二节） 3. 最后看 **IPC、preload、contextIsolation** 如何让 Vue 安全地用主进程能力（第三、四节） 把这三层串起来，后面读项目里的 `main.cjs`、`preload.ts`、Vue 发 IPC 的代码会顺很多。 ]]> http://herong.info/posts/_templates/article http://herong.info/posts/_templates/article Wed, 01 Jan 2025 00:00:00 GMT ]]> http://herong.info/posts/_templates/series-intro http://herong.info/posts/_templates/series-intro Wed, 01 Jan 2025 00:00:00 GMT ]]> http://herong.info/posts/ai-agent-coding-career/mini-codex-v2-open-source-en http://herong.info/posts/ai-agent-coding-career/mini-codex-v2-open-source-en Fri, 19 Jun 2026 00:00:00 GMT build a local Mini Codex -> turn one coding request into a trackable, reviewable, verifiable, replayable engineering task ``` Primary reading page: [Mini Codex course page](https://mianshiti.net/welcome/mini-codex) Open-source repository: [https://github.com/herongdev/min-codex-hands-on-v2](https://github.com/herongdev/min-codex-hands-on-v2) ## Who This Is For This course is for developers who already know basic frontend, backend, or full-stack development and are using tools such as Codex, Cursor, or Claude Code. You do not need to master a complex agent framework first. The more important questions are: ```text Why is a Coding Agent different from a chatbot? Why should the model not touch the file system directly? Why is a prompt not a security boundary? Why should code changes go through a plan and a diff review? Why does "done" require verification evidence? Why do trace and eval decide whether the agent can improve over time? ``` ## What You Will Build By the end of the foundation course, you will have a small but complete Mini Codex: ```text enter one coding request -> save it as a task -> generate a plan -> wait for your approval -> modify files -> run checks -> save the process -> inspect the result in a desktop workbench ``` It does not try to copy every capability of the official Codex product. The foundation course focuses on one thing: making the smallest safe coding-agent loop work. ## Course Outline The open foundation course includes: 1. Lab 00: Environment and practice workspace 2. Lab 01: Save the first task 3. Lab 02: Pause a task for human approval 4. Lab 03: Tool Registry and permission boundaries 5. Lab 04: Make the first real code change 6. Lab 05: Trace, Replay, and Eval 7. Lab 06: Backend API and SSE 8. Lab 07: Desktop workbench 9. Lab 07b: UI polish and design system 10. Lab 08: Compare the boundary with real Codex-style tools 11. Real Codex capability upgrade map 12. Demo cases 13. Eval ledger ## Publishing Boundary This release open-sources the foundation course and the public upgrade direction only. The v2 Advanced course is maintained separately and is not part of this open-source release. The site and repository do not expose private advanced-course paths or commercial-course content. ## Why Start With the Foundation The hard part of AI coding is not asking a model to generate code. The hard part is putting generated code inside an engineering system: ```text state permissions planning review verification replay evaluation ``` Once these foundations are working, RAG, memory, MCP, subagents, Git worktrees, and dashboards become much easier to reason about. Start here: [Open the Mini Codex course page](https://mianshiti.net/welcome/mini-codex) ]]> http://herong.info/posts/ai-agent-coding-career/mini-codex-v2-open-source http://herong.info/posts/ai-agent-coding-career/mini-codex-v2-open-source Fri, 19 Jun 2026 00:00:00 GMT 做出一个本地 Mini Codex -> 让一次代码需求变成可追踪、可审批、可验证、可复盘的工程任务 ``` GitHub 仓库： [https://github.com/herongdev/min-codex-hands-on-v2](https://github.com/herongdev/min-codex-hands-on-v2) ## 适合谁 适合已经会基础前后端开发，并且正在使用 Codex、Cursor、Claude Code 这类 AI 编程工具的人。 你不需要先懂复杂 Agent 框架。更重要的是先理解这些工程问题： ```text 为什么 Coding Agent 不是 Chatbot 为什么模型不能直接碰文件系统 为什么 prompt 不是安全边界 为什么改代码前要先生成计划和 diff 为什么没有 verify 就不能说任务完成 为什么 trace / eval 决定工具能不能持续变好 ``` ## 课程会做出什么 完成基础课后，你会得到一个最小但完整的 Mini Codex： ```text 输入一句代码修改需求 -> 保存任务 -> 给出计划 -> 等你确认 -> 修改文件 -> 运行检查 -> 保存过程 -> 在桌面界面查看 ``` 它不会复制官方 Codex 的全部能力。基础课只追求一件事：把最小闭环跑稳。 ## 课程目录 公开基础课包含： 1. Lab 00：环境准备和练习目录 2. Lab 01：保存第一条任务 3. Lab 02：让任务能停下来等你确认 4. Lab 03：Tool Registry 和权限边界 5. Lab 04：第一次真实代码修改 6. Lab 05：Trace、Replay 和 Eval 7. Lab 06：后端 API 和 SSE 8. Lab 07：桌面工作台 9. Lab 07b：UI 美化和设计系统 10. Lab 08：对照真实 Codex 能力边界 11. 真实 Codex 功能升级包 12. 练习案例 13. 复盘台账 ## 开源边界 本次只开源基础课和公开升级方向。 v2 Advanced 进阶课独立维护，暂不随基础课仓库开源。展示页和 GitHub 仓库也不会公开进阶课目录、私有路径或商业课正文。 ## 为什么先开源基础课 AI 编程真正难的不是让模型生成代码，而是把生成代码这件事放进工程约束里： ```text 有状态 有权限 有计划 有审查 有验证 有回放 有复盘 ``` 先把这些基础能力亲手跑一遍，再讨论 RAG、Memory、MCP、Subagent、Git worktree、质量面板，才不容易把高级名词做成空架子。 下一步从仓库 README 开始： [进入 Mini Codex v2 基础课](https://github.com/herongdev/min-codex-hands-on-v2) ]]> http://herong.info/posts/cpp教程/README http://herong.info/posts/cpp教程/README Mon, 27 Jan 2025 00:00:00 GMT 从 C++ 语法速览到 CMake 实战，再到 NAPI 模块构建，一站式掌握 C++ 原生开发。 ## 📚 教程目录 ### 第一部分：C++ 快速入门 掌握 C++ 常用语法与工程实践。 - [C++ 半小时快速入门（只学最常用的）](./基础入门/C++-半小时快速入门（只学最常用的）.md) ⭐ - `.h` 与 `.cpp` 文件分工 - 常用语法速览 - 类与 RAII 概念 - 智能指针基础 - CMake 最小配置 - `extern "C"` 详解 - [typedef 别名与前向声明冲突：人名比喻详解](./基础入门/typedef别名与前向声明冲突-人名比喻详解.md) ⭐ - typedef 别名 vs struct 前向声明 - 为什么不能前向声明别名 - 两种修复方案（用真名/包含头文件） - 常见错误与最佳实践 ### 第二部分：CMake 构建系统 深入学习 CMake，掌握构建系统配置。 - [CMake 实战：从零到生成动态库](./基础入门/CMake实战：从零到生成动态库.md) ⭐ - CMake 基础概念 - 最简单的 CMake 项目 - 生成动态库 - 完整的 CMake 项目 - 进阶：条件编译和路径管理 - [CMake 实战 2：NAPI 模块构建详解](./基础入门/CMake实战2：NAPI模块构建详解.md) ⭐ - NAPI 模块构建流程 - 第三方库管理 - 头文件路径设置 - 依赖库链接 - 完整实例代码 - [CMake 语法解析：为什么用空格而不是逗号？](./基础入门/CMake语法解析：为什么用空格而不是逗号.md) ⭐ - CMake 语法特点 - 空格 vs 逗号 - 各种分隔方式 - 常见错误与解决方案 ### 第三部分：图形学基础 学习 OpenGL ES 图形渲染基础。 - [EGL 是什么？OpenGL 与系统之间的翻译官](./基础入门/EGL-是什么-OpenGL与系统之间的翻译官.md) ⭐ - EGL 的翻译官角色 - EGLDisplay、EGLSurface、EGLContext - 完整工作流程 - 跨平台兼容性 - [OpenGL ES 3 与 EGL 的区别：工地比喻 + 实战清单](./基础入门/OpenGL-ES-3-与-EGL-区别-工地比喻与实战清单.md) ⭐ - OpenGL ES 3 = 建筑工人 - EGL = 工地办公室 - 工作流程对比 - 版本区别（ES 3 vs ES 2） - [为什么一个面需要 6 个顶点：三角形基础与纸片立方体优化](./基础入门/为什么一个面需要6个顶点-三角形基础与纸片立方体优化.md) ⭐ - GPU 为什么只认三角形 - 矩形 = 2 个三角形 = 6 个顶点 - 纸片立方体优化（避免 Z-fighting） - 三角形绘制的优势 - [顶点着色器与片段着色器：上色师傅比喻详解](./基础入门/顶点着色器与片段着色器-上色师傅比喻详解.md) ⭐ - 顶点着色器 = 定位师傅（管位置） - 片段着色器 = 上色师傅（管颜色） - 完整工作流程 - 数据量对比与分工效率 - [Shader 源是什么：食谱比喻与实战清单](./基础入门/Shader源-是什么-食谱比喻与实战清单.md) ⭐ - Shader 源 = 给 GPU 的“食谱” - 顶点/片段 Shader 职责与流程 - GLSL 示例与项目组织 - 为什么 Shader 提升灵活性和效率 - [3D 开发基础：从零到一的十课（坐标/网格/相机/光照/流水线）](./基础入门/3D开发基础-从零到一的十课-坐标-网格-相机-光照-流水线.md) ⭐ - 坐标系与网格 - 变换矩阵与相机 - 材质/纹理与光照 - GPU 流水线与动画帧率 --- ## 🎯 学习路径 ### 初学者路线 ```text 1. C++ 快速入门 ← 语法基础 ├─ .h 和 .cpp 文件 ├─ 常用标准库（vector, string, algorithm） ├─ 类和 RAII └─ extern "C" 详解 2. CMake 基础 ← 构建系统 ├─ Hello CMake ├─ 生成动态库 └─ 文件组织 3. CMake 实战 ← NAPI 应用 ├─ 第三方库管理 ├─ 依赖链接 └─ NAPI 模块构建 4. 语法深入 ← 理解规则 └─ CMake 语法特点 ``` ### 进阶开发者路线 ```text 1. NAPI 开发 2. HarmonyOS 原生模块 3. 性能优化 4. 多平台构建 ``` ### 图形学路线 ```text 1. EGL 基础 ← 图形环境 └─ EGL 是什么、如何初始化 2. OpenGL ES 3 ← 绘制技术 └─ OpenGL ES 3 vs EGL 区别 3. 图形学基础 ← 渲染原理 ├─ 为什么用三角形（6顶点/面） ├─ 顶点着色器（定位） └─ 片段着色器（上色） ``` --- ## 💡 特色内容 ### ⭐ C++ 半小时快速入门 **核心内容**： - 为什么有 `.cpp` 和 `.h` 文件？ - 多文件工程与头文件用法 - 最常用语法速览 - 类（最常用子集）与 RAII 概念 - 智能指针（unique_ptr） - CMake 最小配置 - `extern "C"` 详解 **适合人群**： - 会写代码但没学过 C++ - 需要快速上手 C++ 语法 - 准备学习 NAPI 开发 **学习收获**： - 掌握 C++ 常用语法（30 分钟） - 理解 `.h` 和 `.cpp` 的作用 - 学会使用 CMake 构建项目 - 了解 `extern "C"` 的作用 ### ⭐ CMake 从零到生成动态库 **核心内容**： - CMake 是什么？ - Hello CMake 项目 - CMake 核心概念 - 生成动态库 - 多文件项目 - 条件编译与路径管理 **适合人群**： - 第一次接触 CMake - 需要配置构建系统 - 准备做 NAPI 开发 **学习收获**： - 从零掌握 CMake - 生成自己的动态库 - 理解构建流程 - 掌握常用命令 ### ⭐ NAPI 模块构建详解 **核心内容**： - 项目结构设计 - 主 CMakeLists.txt 逐行详解 - 第三方库管理（add_subdirectory） - NAPI 模块构建（add_library） - 头文件路径管理 - 依赖库链接 - 完整实例代码 **适合人群**： - 要做 HarmonyOS NAPI 开发 - 需要链接第三方库 - 想理解构建系统 **学习收获**： - 掌握 NAPI 模块构建 - 理解依赖管理 - 学会组织多文件项目 - 能调试构建问题 ### ⭐ CMake 语法解析 **核心内容**： - 为什么用空格而不是逗号？ - CMake 的"方言"特点 - 各种分隔方式 - 与其他语言对比 - 常见错误与解决方案 **适合人群**： - 对 CMake 语法感到困惑 - 来自其他编程语言 - 想深入理解 CMake **学习收获**： - 理解 CMake 设计哲学 - 掌握语法规则 - 避免常见错误 - 写出规范的 CMakeLists.txt ### ⭐ 图形学基础系列 **核心内容**： - EGL 是什么（翻译官角色） - OpenGL ES 3 vs EGL（工地比喻） - 为什么一个面需要 6 个顶点（三角形基础） - 顶点着色器与片段着色器（上色师傅比喻） **适合人群**： - 做 HarmonyOS 3D 图形开发 - 学习 OpenGL ES 渲染 - 理解着色器原理 **学习收获**： - 理解 EGL 的作用与初始化流程 - 掌握 OpenGL ES 3 基本概念 - 理解三角形渲染原理 - 掌握顶点着色器和片段着色器的分工 --- ## 📖 使用指南 ### 如何阅读本教程 1. **按需学习**：根据目录选择需要的章节 2. **循序渐进**：建议按照学习路线顺序学习 3. **动手实践**：每篇文章都有完整代码示例 4. **查漏补缺**：可作为速查手册使用 ### 学习顺序建议 **快速上手**： ```text C++ 快速入门 → CMake 基础 → NAPI 构建 ``` **深入学习**： ```text C++ 快速入门 → CMake 基础 → CMake 实战 → 语法解析 ``` **专项学习**： - 只学 C++：阅读 "C++ 快速入门" - 只学 CMake：阅读 "CMake 从零到生成动态库" - 只学 NAPI：阅读 "NAPI 模块构建详解" --- ## 🔧 开发环境 ### 推荐配置 - **C++ 编译器**：GCC/Clang - **CMake**：3.16 以上 - **编辑器**：VSCode / CLion / DevEco Studio - **操作系统**：Windows / Linux / macOS / HarmonyOS ### 快速搭建 1. 安装 C++ 编译器（随操作系统自带或下载） 2. 安装 CMake 3. 创建第一个项目 4. 按照教程实践 --- ## 📝 更新日志 - **2025-01-27**：创建教程目录结构 - **2025-01-27**：添加 C++ 快速入门 - **2025-01-27**：添加 CMake 实战教程 - **2025-01-27**：添加 NAPI 模块构建详解 - **2025-01-27**：添加 CMake 语法解析 - **2025-01-27**：添加图形学基础系列 - EGL 是什么（翻译官比喻） - OpenGL ES 3 与 EGL 区别（工地比喻） - 为什么一个面需要 6 个顶点（三角形基础） - 顶点着色器与片段着色器（上色师傅比喻） - **2025-01-27**：添加 C++ 进阶主题 - typedef 别名与前向声明冲突（人名比喻） - Shader 源是什么（食谱比喻） - 3D 开发基础（十课入门） --- ## 🤝 贡献指南 欢迎贡献内容！ ### 贡献方式 - 提交 Issue 反馈问题 - 提交 Pull Request 改进内容 - 分享学习心得 ### 内容规范 - 代码示例完整可运行 - 注释详细规范 - 排版美观统一 - 使用大白话解释 --- ## 🔗 相关资源 ### 官方文档 - [C++ 标准](https://isocpp.org/) - [CMake 文档](https://cmake.org/documentation/) - [HarmonyOS 开发者官网](https://developer.huawei.com/consumer/cn/harmonyos/) ### 学习资源 - [C++ 参考](https://zh.cppreference.com/) - [CMake 教程](https://cmake.org/cmake/help/latest/guide/tutorial/index.html) - [NAPI 示例](https://gitee.com/openharmony-sig/napi-examples) ### 工具推荐 - [VSCode](https://code.visualstudio.com/) - 轻量级编辑器 - [CLion](https://www.jetbrains.com/clion/) - 专业的 C++ IDE - [CMake Tools](https://cmake.org/cmake/help/latest/manual/cmake.1.html) - VSCode 插件 --- ## 📧 联系方式 - **技术分享**：[herong.info](https://herong.info) - **问题反馈**：通过 Issue 或评论区 --- **让我们一起掌握 C++ 与 CMake！** 🚀 ]]> http://herong.info/posts/c教程/README http://herong.info/posts/c教程/README Sat, 04 Jul 2026 00:00:00 GMT 基于 Duc-Tam Nguyen 的 [The Little Book of C](https://little-book-of.github.io/c/books/en-US/book.html)（[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)） 这套教程不只适合通读概念。你会从 `printf` 开始，逐步完成计算器、手动内存管理、小型数据结构、文件日志工具、Makefile、Mini Shell、调试修复、可移植多线程程序，最后交付一个可以构建、运行、测试、打包和说明取舍的 C 小项目。 完成后，你应该能把 C 代码从“能跑”推进到“可维护、可调试、可交付”： - 设计一个小型命令行工具，拆分 `.c` / `.h` 文件，并用 Makefile 稳定构建。 - 解释栈、堆、指针、生命周期、深浅拷贝和未定义行为对程序正确性的影响。 - 用警告、断言、调试器、内存检查和代码审查清单定位问题。 - 处理文件 I/O、错误码、命令行参数、系统调用、进程、管道和信号。 - 为最终项目留下可展示证据：源码、构建命令、运行输出、测试记录、调试记录、README 和版本标签。 这份证据可以用于作品集、代码面试复盘、系统编程入门项目，或后续学习操作系统、数据库、编译器、嵌入式开发时的基础练习。它不能保证职位或录用结果，但能证明你已经动手完成过 C 项目的核心工程流程。 ## 固定练习工作区 所有练习统一放在同一个工作区，避免命令输出散落在教程目录里。 macOS / Linux: ```bash mkdir -p ~/c-course-labs cd ~/c-course-labs ``` Windows PowerShell: ```powershell New-Item -ItemType Directory -Force "$HOME\c-course-labs" Set-Location "$HOME\c-course-labs" ``` 每个练习单独创建目录，例如 `020-calculator`、`060-makefile-lab`、`100-tinynotes`。每章完成后，把运行命令、关键输出、遇到的问题和下一步改进写进该目录下的 `evidence.md`。 ## 编译标准选择 默认练习建议使用更稳妥的 C17： ```bash gcc -std=c17 -Wall -Wextra -Wpedantic -g main.c -o main ``` 课程中涉及 C23 的章节会把它作为现代能力或可选升级来练。GCC 文档说明 C23 可用 `-std=c23` 选择，Clang 的 C 支持页把 C23 标为部分支持；因此做跨编译器练习时，先用 C17 保证主线能跑，再用 C23 对照新特性和兼容性。 - Source: [GCC language standards](https://gcc.gnu.org/onlinedocs/gcc/Standards.html) - Source: [Clang C language status](https://clang.llvm.org/c_status.html) ## 选择语言 | 语言 | 目录 | 说明 | |------|------|------| | **中文** | [zh-CN 教程总览](./zh-CN/README.md) | 适合中文跟练，保留原书代码并补充课程化学习路径 | | **English** | [en-US Index](./en-US/README.md) | English path with the same hands-on contract | ## 章节对照 | 英文章节 | 中文章节 | |----------|----------| | 01-Getting Started | 01-入门 | | 02-Language Basics | 02-语言基础 | | 03-Working with Memory | 03-内存 | | 04-Structuring Data | 04-数据结构 | | 05-Input Output and Files | 05-输入输出与文件 | | 06-Compilation and Build | 06-编译与构建 | | 07-Working Close to the System | 07-贴近系统 | | 08-Debugging Testing Profiling | 08-调试测试与 profiling | | 09-Portable and Modern C | 09-可移植与现代 C | | 10-Building Real Projects | 10-真实项目 | | 11-Epilogue | 11-结语 | 每篇文章顶部可切换 **中文 / English**（`alternateZh` / `alternateEn`）。 ]]> http://herong.info/posts/flutter教程/README http://herong.info/posts/flutter教程/README Mon, 27 Jan 2025 00:00:00 GMT 本系列教程将带你从零开始学习 Flutter 开发，涵盖基础入门、进阶实战、性能优化、架构设计等全方位内容。 ## 📚 教程结构 ### 第一部分：基础入门 适合完全零基础的初学者，快速掌握 Flutter 开发基础。 - [1.1 Flutter 环境搭建与项目创建](./01-基础入门/01-环境搭建.md) - [1.2 Dart 语言快速入门](./01-基础入门/02-Dart语言基础.md) - [1.3 Widget 基础：StatelessWidget 与 StatefulWidget](./01-基础入门/03-Widget基础.md) - [1.4 布局系统：Container、Row、Column、Stack](./01-基础入门/04-布局系统.md) - [1.5 常用组件：Text、Image、Button、TextField](./01-基础入门/05-常用组件.md) - [1.6 导航与路由](./01-基础入门/06-导航路由.md) - [1.7 生命周期详解](./01-基础入门/07-生命周期.md) - [1.8 Dart 算法技巧：笛卡尔积生成](./01-基础入门/08-Dart算法技巧-笛卡尔积生成.md) ⭐ - [1.9 Dart Iterable 与惰性计算：map().toList() 详解](./01-基础入门/09-Dart-Iterable与惰性计算.md) ⭐ ### 第二部分：核心概念 深入理解 Flutter 的核心机制和设计理念。 - [2.1 Widget 树、Element 树、RenderObject 树](./02-核心概念/01-三棵树.md) - [2.2 BuildContext 深度解析](./02-核心概念/02-BuildContext.md) - [2.3 State 管理入门](./02-核心概念/03-State管理入门.md) - [2.4 Key 的作用与使用场景](./02-核心概念/04-Key详解.md) - [2.5 InheritedWidget 原理](./02-核心概念/05-InheritedWidget.md) - [2.6 WidgetsBinding 与调度机制](./02-核心概念/06-WidgetsBinding详解.md) ⭐ - [2.7 帧回调与生命周期钩子](./02-核心概念/07-帧回调机制.md) ⭐ ### 第三部分：状态管理 掌握 Flutter 中各种状态管理方案。 - [3.1 setState 的正确使用](./03-状态管理/01-setState详解.md) - [3.2 Provider 完整指南](./03-状态管理/02-Provider.md) - [3.3 Riverpod 入门与实战](./03-状态管理/03-Riverpod入门.md) ⭐ - [3.4 Riverpod Provider Family 详解](./03-状态管理/04-ProviderFamily.md) ⭐ - [3.5 Riverpod 最佳实践](./03-状态管理/05-Riverpod最佳实践.md) ⭐ - [3.6 Bloc 模式详解](./03-状态管理/06-Bloc.md) - [3.7 GetX 快速上手](./03-状态管理/07-GetX.md) - [3.8 状态管理方案对比](./03-状态管理/08-方案对比.md) ### 第四部分：异步与数据 处理异步操作、网络请求和数据持久化。 - [4.1 Future 与 async/await](./04-异步数据/01-Future详解.md) - [4.2 Stream 详解](./04-异步数据/02-Stream.md) - [4.3 网络请求：Dio 使用指南](./04-异步数据/03-网络请求.md) - [4.4 JSON 序列化与反序列化](./04-异步数据/04-JSON处理.md) - [4.5 本地存储：SharedPreferences](./04-异步数据/05-本地存储.md) - [4.6 数据库：sqflite 使用](./04-异步数据/06-数据库.md) ### 第五部分：UI 进阶 掌握复杂 UI 的实现技巧。 - [5.1 自定义 Widget](./05-UI进阶/01-自定义Widget.md) - [5.2 动画系统：Animation、AnimationController](./05-UI进阶/02-动画系统.md) - [5.3 手势识别与触摸事件](./05-UI进阶/03-手势识别.md) - [5.4 ListView 与 GridView 性能优化](./05-UI进阶/04-列表优化.md) - [5.5 Sliver 家族详解](./05-UI进阶/05-Sliver.md) - [5.6 主题与样式管理](./05-UI进阶/06-主题样式.md) - [5.7 响应式设计](./05-UI进阶/07-响应式设计.md) ### 第六部分：平台交互 实现 Flutter 与原生平台的通信。 - [6.1 Platform Channel 基础](./06-平台交互/01-PlatformChannel基础.md) - [6.2 MethodChannel 详解](./06-平台交互/02-MethodChannel.md) - [6.3 EventChannel 详解](./06-平台交互/03-EventChannel.md) - [6.4 原生插件开发](./06-平台交互/04-插件开发.md) - [6.5 调用原生 API](./06-平台交互/05-调用原生API.md) ### 第七部分：测试与调试 确保代码质量和应用稳定性。 - [7.1 单元测试](./07-测试调试/01-单元测试.md) - [7.2 Widget 测试](./07-测试调试/02-Widget测试.md) - [7.3 集成测试](./07-测试调试/03-集成测试.md) - [7.4 调试技巧与工具](./07-测试调试/04-调试技巧.md) - [7.5 性能分析](./07-测试调试/05-性能分析.md) ### 第八部分：性能优化 提升应用性能和用户体验。 - [8.1 渲染性能优化](./08-性能优化/01-渲染优化.md) - [8.2 内存管理](./08-性能优化/02-内存管理.md) - [8.3 包体积优化](./08-性能优化/03-包体积优化.md) - [8.4 启动速度优化](./08-性能优化/04-启动优化.md) - [8.5 图片加载优化](./08-性能优化/05-图片优化.md) ### 第九部分：架构设计 构建可维护、可扩展的应用架构。 - [9.1 项目结构设计](./09-架构设计/01-项目结构.md) - [9.2 MVVM 架构实践](./09-架构设计/02-MVVM.md) - [9.3 依赖注入](./09-架构设计/03-依赖注入.md) - [9.4 路由管理](./09-架构设计/04-路由管理.md) - [9.5 错误处理](./09-架构设计/05-错误处理.md) - [9.6 日志系统](./09-架构设计/06-日志系统.md) ### 第十部分：实战项目 通过完整项目巩固所学知识。 - [10.1 项目一：Todo 应用](./10-实战项目/01-Todo应用.md) - [10.2 项目二：新闻客户端](./10-实战项目/02-新闻客户端.md) - [10.3 项目三：电商应用](./10-实战项目/03-电商应用.md) - [10.4 项目四：社交应用](./10-实战项目/04-社交应用.md) --- ## 🎯 学习路径建议 ### 初学者路径（1-2 个月） 1. **第一部分：基础入门** → 掌握基本语法和组件 2. **第二部分：核心概念**（前 5 章） → 理解核心机制 3. **第三部分：状态管理**（前 3 章） → 学会管理状态 4. **第十部分：项目一** → 实践巩固 ### 进阶开发者路径（2-3 个月） 1. 复习基础部分 2. **第二部分：核心概念**（完整） → 深入理解机制 3. **第三部分：状态管理**（完整） → 掌握各种方案 4. **第四部分：异步与数据** → 处理网络和数据 5. **第五部分：UI 进阶** → 复杂 UI 实现 6. **第十部分：项目二、三** → 综合实战 ### 高级开发者路径（持续学习） 1. **第六部分：平台交互** → 原生能力 2. **第七部分：测试与调试** → 代码质量 3. **第八部分：性能优化** → 性能提升 4. **第九部分：架构设计** → 工程化 5. **第十部分：项目四** → 大型应用 --- ## 📖 如何使用本教程 ### 学习方式 1. **循序渐进**：按章节顺序学习，打好基础 2. **动手实践**：每个章节都要敲代码，运行示例 3. **理解原理**：不要只记 API，要理解背后原理 4. **项目驱动**：学完理论立即做项目巩固 ### 代码规范 - 所有示例代码都经过测试验证 - 关键代码行都有中文注释 - 提供完整可运行的代码示例 - 标注常见坑点和最佳实践 ### 标记说明 - ⭐：本文档相关章节 - 🔥：重点章节 - 💡：实用技巧 - ⚠️：常见陷阱 --- ## 💬 反馈与贡献 如果您在学习过程中遇到问题，或者有好的建议，欢迎： - 提交 Issue - 提交 Pull Request - 在评论区讨论 --- ## 📝 更新日志 - **2025-01-27**：创建教程目录结构 - **2025-01-27**：添加 WidgetsBinding 与 Riverpod 相关章节 - **2025-01-27**：添加 Dart 算法技巧：笛卡尔积生成 - **2025-01-27**：添加 Dart Iterable 与惰性计算详解 --- ## 🔗 相关资源 - [Flutter 官方文档](https://flutter.dev/docs) - [Dart 官方文档](https://dart.dev/guides) - [Riverpod 文档](https://riverpod.dev/) - [Flutter 中文社区](https://flutter.cn/) --- **祝你学习顺利，成为 Flutter 开发高手！** 🚀 ]]> http://herong.info/posts/harmonyos教程/ArkTS-HTML三种通信方式-WebView双向通信实战 http://herong.info/posts/harmonyos教程/ArkTS-HTML三种通信方式-WebView双向通信实战 Thu, 30 Oct 2025 00:00:00 GMT { // 推数据 const data = [{ question: '人生', percent: 0.38 }]; this.controller.runJavaScript( `window.LifeChart && window.LifeChart.setData(${JSON.stringify(data)})` ); // 取网页返回值（如读取 document.title） this.controller.runJavaScriptExt('document.title').then(result => { const title = result.getString(); // ArkWeb JsValue console.info('[WebTitle]', title); }); }); ``` > 要点：把注入放在 `onPageEnd` 等网页完成回调之后，避免目标函数尚未挂载。（[华为开发者官网][1]） --- ## 2) 网页调用 ArkTS（注入原生对象） **什么时候用**：H5 希望直接触发原生能力（如读取设置、调用端能力等）。 - **初始化时注入：**`javaScriptProxy`（Web 组件属性） - **初始化完成后注入：**`controller.registerJavaScriptProxy(...)` 这两个都能把 ArkTS 对象“挂”到前端环境里（通常是 `window.XXX`），JS 直接调你暴露的方法。（[华为开发者官网][3]） **示例（ArkTS，在 `onControllerAttached` 里注册）：** ```ts this.controller.registerJavaScriptProxy({ name: "NativeBridge", // 前端可直接调用 NativeBridge.xxx() methodList: ["hello", "update"], object: { hello: (): string => { return "Hi from ArkTS"; }, update: (json: string): void => { // 处理来自 H5 的数据 // ... 更新 Store 或执行业务 }, }, }); ``` **示例（网页 JS 调用原生）：** ```js // H5 const msg = window.NativeBridge.hello(); window.NativeBridge.update(JSON.stringify({ age: 30 })); ``` > 官方文档场景叫“前端页面调用应用侧函数”，支持 **`javaScriptProxy`** 与 **`registerJavaScriptProxy()`** 两种注入时机。（[OpenHarmony][4]） --- ## 3) 双向消息通道（更通用/更安全） **什么时候用**：需要**持续**、**双工**传递数据（如事件流、较大 JSON），且不想暴露大量同步方法。 - 建通道：`controller.createWebMessagePorts()` - 发送端口到 H5：`controller.postMessage(...)`（把其中一个端口发给网页） - 收消息/发消息：ArkTS 侧 `WebMessagePort.onMessageEvent / postMessageEvent`；H5 侧使用 `MessagePort` 的 `onmessage / postMessage`。（[cnblogs.com][5]） **ArkTS（建立通道并把端口发给 H5）：** ```ts const ports = this.controller.createWebMessagePorts(); ports[1].onMessageEvent((msg) => { const payload = msg.getString ? msg.getString() : ""; console.info("[H5->ETS]", payload); }); // 把 ports[0] 发给网页，网页保存后即可双向通信 this.controller.postMessage("__init_port__", [ports[0]], "*"); ``` **H5（接收端口并通信）：** ```js let h5Port = null; window.addEventListener("message", (e) => { if (e.data === "__init_port__" && e.ports?.[0]) { h5Port = e.ports[0]; h5Port.onmessage = (evt) => console.log("[ETS->H5]", evt.data); // 向 ArkTS 发消息 h5Port.postMessage(JSON.stringify({ type: "PING" })); } }); ``` > 该方案基于 **WebMessagePort**，自 API9 起提供，适合做**持久双工**通道；官方也推荐用消息通道替代过度的对象注入以提升安全性。（[cnblogs.com][5]） --- ## 4) 其它有用回调 - `onPageBegin / onPageEnd / onProgressChange`：注入时机与进度控制。（[CSDN 博主][6]） - `onConsole / onAlert / onConfirm / onPrompt`：接管网页日志与弹框（便于调试与原生 UI 替换）。（[华为开发者官网][7]） --- ## 5) 选型建议（实践经验） - **推数据到 H5**：优先 `runJavaScript*`，简单直接（我们前面给你的 G2 图表就是这样做）。（[Medium][8]） - **H5 触发原生能力**：少量方法用 `registerJavaScriptProxy`；多而频的交互更建议 **消息通道**。（[华为开发者官网][9]） - **时机**：所有注入/调用尽量放在 `onPageEnd` 之后。（[华为开发者官网][1]） 如果你要，我可以把这三种方式的**最小模板**直接嵌到你现有的 `LifeChart` 组件和 `index.html` 里，按你现在的项目结构一键跑通。 [1]: https://developer.huawei.com/consumer/cn/forum/topic/0210121903108098084?utm_source=chatgpt.com "10、OpenHarmony Web子系统开发常见问题-华为开发者话题" [2]: https://developer.huawei.com/consumer/en/doc/best-practices/bpta-harmony-application-security?utm_source=chatgpt.com "Application Security Coding-Application ..." [3]: https://developer.huawei.com/consumer/en/codelab/HarmonyOS-WebView/?utm_source=chatgpt.com "Using WebView" [4]: https://docs.openharmony.cn/pages/v4.1/en/application-dev/web/web-in-page-app-function-invoking.md?utm_source=chatgpt.com "Invoking Application Functions on the Frontend Page" [5]: https://www.cnblogs.com/hencins/p/17623151.html?utm_source=chatgpt.com "调研capacitor兼容openharmony平台可行性- 汪淼焱" [6]: https://blog.csdn.net/yong_19930826/article/details/146799987?utm_source=chatgpt.com "Harmonyos之加载本地web页面原创" [7]: https://developer.huawei.com/consumer/en/doc/harmonyos-guides/web-dialog?utm_source=chatgpt.com "Displaying Web Page Dialog Boxes" [8]: https://medium.com/%40yang45472/call-the-front-end-page-function-f9dbe24141c2?utm_source=chatgpt.com "Call the front-end page function | by Yang" [9]: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/web-in-page-app-function-invoking-V13?utm_source=chatgpt.com "前端页面调用应用侧函数" ]]> http://herong.info/posts/harmonyos教程/ArkTS-使用-ohos.net.http-实现SSE-requestInStream-最小改动 http://herong.info/posts/harmonyos教程/ArkTS-使用-ohos.net.http-实现SSE-requestInStream-最小改动 Wed, 15 Oct 2025 00:00:00 GMT 场景：把原先用 `fetch` 读 `text/event-stream` 的代码，替换为鸿蒙官方 `@ohos.net.http` 的**流式**实现。 ```ts // ① 引入官方 HTTP 与 util.TextDecoder import http from "@ohos.net.http"; import util from "@ohos.util"; export interface SSEOptions { onData: (chunk: string) => void; onDone?: () => void; onError?: (err: Error) => void; headers?: Record; body?: object | string | number | boolean | null; // ArkTS 下没有浏览器 AbortSignal，这里按你的工程自定义（可选） signal?: { aborted?: boolean }; } // 【复杂逻辑】使用 requestInStream 开启流式请求；用 dataReceive 持续取块 export async function startSSEStream( url: string, options: SSEOptions ): Promise { const httpRequest = http.createHttp(); const decoder = util.TextDecoder.create("utf-8"); // 鸿蒙的 TextDecoder let buffer = ""; // ② 事件订阅（先订阅，再发起），逐块解析 \n\n 分帧与 data: 行 httpRequest.on("dataReceive", (ab: ArrayBuffer) => { // 【复杂逻辑】保持解码器状态，避免中文被截断 const text = decoder.decode(new Uint8Array(ab), { stream: true } as any); buffer += text; const frames = buffer.split("\n\n"); buffer = frames.pop() ?? ""; for (const frame of frames) { if (!frame.trim()) continue; for (const line of frame.split("\n")) { if (line.startsWith("data:")) { const payload = line.slice(5).trim(); if (payload === "[DONE]") { options.onDone?.(); // 结束：可选择取消/销毁 try { httpRequest.destroy(); } catch {} return; } // 【复杂逻辑】尽量按 JSON 解析；失败则按纯文本 try { const data = JSON.parse(payload); if (data?.type === "chunk" && data.text) options.onData(data.text); else if (data?.type === "done") { options.onDone?.(); try { httpRequest.destroy(); } catch {} } else if (data?.type === "error") throw new Error(data.text || "服务端错误"); else options.onData(payload); } catch { options.onData(payload); } } } } }); httpRequest.on("dataEnd", () => { options.onDone?.(); try { httpRequest.destroy(); } catch {} }); httpRequest.on("headersReceive", (_hdrs) => { // 可选：校验响应码/头部 }); httpRequest.on("dataReceiveProgress", (_p) => { // 可选：进度 }); // ③ 以流式方式发起请求（POST/GET 都可；SSE 常见为 GET，但你后端也支持 POST） try { await httpRequest.requestInStream(url, { method: http.RequestMethod.POST, // 或 GET，按你的服务端 header: { Accept: "text/event-stream", "Content-Type": "application/json", ...(options.headers ?? {}), }, // 【复杂逻辑】体可为字符串；对象转 JSON extraData: typeof options.body === "string" ? options.body : options.body == null ? "" : JSON.stringify(options.body), // 超时、证书等可按需配置 connectTimeout: 60000, readTimeout: 0, // SSE 不超时读 }); } catch (e) { const err = e instanceof Error ? e : new Error(String(e)); options.onError?.(err); try { httpRequest.destroy(); } catch {} throw err; } } ``` **同时别忘了权限**（`module.json5` 或 `config.json`）里声明上网权限： ```json { "module": { "reqPermissions": [{ "name": "ohos.permission.INTERNET" }] } } ``` 官方“使用 HTTP 访问网络/发送网络请求”文档均有说明需声明网络权限。[华为开发者网站][5] --- ## 关键依据（官方文档/页面） - **发送网络请求（ArkTS 指南）**：介绍 ArkTS 下如何发送 HTTP 请求。[华为开发者网站][1] - **`@ohos.net.http` API 参考**：官方的 HTTP 模块说明（含 `requestInStream`、事件）。[华为开发者网站][4] - **API 变更页**：明确存在 `on("dataReceive")` 等事件（用于流式响应）。[华为开发者网站][2] - **论坛答复**：确认**只有 `requestInStream`** 支持进度/流式监听。[华为开发者网站][6] - **`@ohos.util` 的 `TextDecoder`**：鸿蒙环境的解码器应从 util 使用。[华为开发者网站][3] --- 如果你愿意，我可以把你现有的 `fetch` 版 **逐行替换** 成上面的 `@ohos.net.http` 版，并只发“需要修改的片段”。 [1]: https://developer.huawei.com/consumer/en/doc/harmonyos-guides/remote-communication-netsend-arkts?utm_source=chatgpt.com "Sending a Network Request (ArkTS)" [2]: https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/js-apidiff-networkkit-hdc?utm_source=chatgpt.com "Network Kit-HarmonyOS NEXT Developer Beta1引入的API ..." [3]: https://developer.huawei.com/consumer/en/doc/harmonyos-references-V5/js-apis-util-V5?utm_source=chatgpt.com "ohos.util (util)" [4]: https://developer.huawei.com/consumer/en/doc/harmonyos-references-V5/js-apis-http-0000001861887649-V5?catalogVersion=V5&utm_source=chatgpt.com "ohos.net.http (Data Request)" [5]: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/http-request?utm_source=chatgpt.com "使用HTTP访问网络" [6]: https://developer.huawei.com/consumer/cn/forum/topic/0204192989342354394?utm_source=chatgpt.com "华为开发者问答" ]]> http://herong.info/posts/harmonyos教程/HarmonyOS ArkTS（.ets）与 TypeScript 的差异速修：定位并修掉你截图里的 15 个问题 http://herong.info/posts/harmonyos教程/HarmonyOS ArkTS（.ets）与 TypeScript 的差异速修：定位并修掉你截图里的 15 个问题 Wed, 15 Oct 2025 00:00:00 GMT 说明：**函数参数**里尽量也不要用解构；能提前取出再用更稳。 --- ### 3) `arkts-no-spread`：不支持对象/数组展开 **TS 写法（问题点）** ```ts headers: { 'Content-Type': 'application/json', 'Accept': 'text/event-stream', ...(headers || {}) } ``` **ETS 改法** ```ts // 【复杂逻辑】用显式赋值循环代替对象展开 const hdrs: Record = { "Content-Type": "application/json", Accept: "text/event-stream", }; if (headers) { for (const k in headers) { if (Object.prototype.hasOwnProperty.call(headers, k)) { hdrs[k] = headers[k]; } } } // 使用 hdrs ``` --- ### 4) `arkts-no-globalthis`：不支持 `globalThis` **TS 写法（问题点）** ```ts const hasFetch = typeof (globalThis as any).fetch === "function"; const canStream = !!(globalThis as any).ReadableStream; ``` **ETS 改法（两种任选其一）** **A. 延迟验证 + try/catch（推荐）** ```ts // 【复杂逻辑】用 try/catch 做能力探测，避免直接引用全局名导致类型报错 let hasTextDecoder = true; try { new TextDecoder("utf-8"); } catch (_) { hasTextDecoder = false; } ``` **B. 直接使用标识符 + 编译期最小声明** ```ts // 声明放在文件顶部：让编译器知道有这些全局（不会生成运行时代码） declare function fetch(...args: any[]): Promise; declare class TextDecoder { constructor(label?: string); decode(u8?: Uint8Array, opts?: { stream?: boolean }): string; } // 代码里直接使用 fetch/TextDecoder，而不是 globalThis.fetch ``` --- ### 5) `Cannot find name 'AbortSignal'/'TextDecoder'/'Response'/'fetch'` **原因**：ArkTS 默认不带 DOM lib。需要**最小类型声明**（仅供编译通过，不产生 JS）。 **在文件顶部追加（或独立 `types.d.ts` 引入）** ```ts // ===== 最小类型声明：零运行时开销 ===== interface AbortSignalLike { aborted?: boolean; } interface ReadableStreamReaderLike { read(): Promise<{ value?: Uint8Array; done: boolean }>; cancel(): Promise | void; } interface ReadableStreamLike { getReader(): ReadableStreamReaderLike; } interface ResponseLike { ok: boolean; status: number; body: ReadableStreamLike | null; } declare function fetch( input: string, init: { method: "POST"; headers: Record; body?: string; signal?: AbortSignalLike; } ): Promise; declare class TextDecoder { constructor(label?: string); decode(input?: Uint8Array, options?: { stream?: boolean }): string; } ``` > 如果你已在工程里集中管理类型声明，建议放到 `global.d.ts` 并在编译配置里包含它。 --- ### 6) `arkts-no-any-unknown`（二次命中）：参数/返回类型补全 **TS 写法（问题点）** ```ts onError?: (err: Error) => void; // catch (err) { onError && onError(err as Error); } ``` **ETS 改法** ```ts // 【复杂逻辑】缩小 err 的类型范围，避免 unknown/any 传播 catch (e) { const error = e instanceof Error ? e : new Error(String(e)); if (onError) onError(error); throw error; } ``` --- ### 7) 其它细节建议（避免触发更多规则） - **不要使用参数解构**，例如 `function foo({a, b}: {a:number;b:number})`，改成普通参数后在函数体内取出。 - **避免可选链的链式陷阱**（部分旧运行时行为差异），关键路径宁愿 `if`。 - **字符串模板里不要拼太复杂表达式**，出问题就抽变量。 --- ## 最小可运行片段（对照） > 目标：在 ArkTS 环境内稳定读取 SSE 的 `ReadableStream`，并保证中文不被截断。 **TS 常见写法（会报你截图那类错）** ```ts const { value, done } = await reader.read(); buffer += decoder.decode(value, { stream: true }); ``` **ETS 兼容写法** ```ts // 【复杂逻辑】避免解构；逐项取值更稳 const r = await reader.read(); const done = r.done; const value = r.value; if (value) { // 【复杂逻辑】保持解码器状态以避免中文被截断 buffer += decoder.decode(value, { stream: true }); } ``` --- ## “问题 ↔ 解决策略”总表（速查） | 报错/限制 | 触发场景 | 修法 | | ---------------------------- | --------------------- | --------------------------------------------- | | `arkts-no-any-unknown` | `any`/`unknown` | 改精确联合类型；`catch` 中收敛为 `Error` | | `arkts-no-destruct-decls` | `const {a}=...` | 先接 `result`，再 `result.a` | | `arkts-no-spread` | `{...obj}`/`[...arr]` | 用 `for-in` 明确复制；数组用 `push/apply` | | `arkts-no-globalthis` | `globalThis.xxx` | 直接用标识符 + `declare`，或 `try/catch` 探测 | | `Cannot find name 'fetch'/…` | 缺 DOM lib | 写最小 `declare` 接口/类 | | `ReadableStream` 相关 | 类型不见 | 自定义 `ReadableStreamLike` 接口 | --- ## 常见坑位答疑 - **Q：我真的不能用解构吗？** A：**变量声明处**不要用（`const {a}=...`），函数体内临时变量赋值后再解构式访问是可以被替代的；这样最稳。 - **Q：`globalThis` 为啥不行？** A：ArkTS Lint 默认禁，它既影响多端一致性也容易引出缺失类型。用最小 `declare` + 直接标识符更干净。 - **Q：最小类型声明会不会影响运行时？** A：不会。`declare` 仅在编译期存在，不会生成任何代码。 --- ## 结语 照着上面的**对照式最小改动**把你的 SSE 客户端改一遍，就能把截图里的 15 个问题一次清干净。后续在 ArkTS 写代码的心法是：**少糖、多显式、类型精确、能力探测用 try/catch**。如果你把某段 TS 写法改不过来，丢给我那一小段——我只回你**必要的改动片段**，并在复杂逻辑上一行加注释。 ]]> http://herong.info/posts/harmonyos教程/HarmonyOS 工程主要配置文件区别：hvigorfile、build-profile、oh-package、app.json5 http://herong.info/posts/harmonyos教程/HarmonyOS 工程主要配置文件区别：hvigorfile、build-profile、oh-package、app.json5 Wed, 27 May 2026 00:00:00 GMT 当前这个工程应该按什么类型来构建。 普通 HarmonyOS 应用一般应该是： ```ts export { appTasks } from '@ohos/hvigor-ohos-plugin'; ``` 你的截图里之前是： ```ts export { AppTasksForArkUIX } from '@ohos/hvigor-ohos-arkui-x-plugin'; ``` 这表示当前工程被识别成了 **ArkUI-X 跨端工程**，所以它会要求配置： ```text arkui-x.dir ``` 或者环境变量： ```text ARKUIX_SDK_HOME ``` 如果你不要跨端，就不应该使用 ArkUI-X 插件。 ### 普通 HarmonyOS 应用应该改成 ```ts export { appTasks } from '@ohos/hvigor-ohos-plugin'; ``` --- ## 三、`apps/harmony/entry/hvigorfile.ts` 这个文件是 **entry 模块级构建入口**。 它告诉 Hvigor： > entry 这个模块应该怎么打包。 普通应用的 entry 模块一般是： ```ts export { hapTasks } from '@ohos/hvigor-ohos-plugin'; ``` 含义是： ```text 把 entry 模块构建成 HAP 包 ``` ### 和根目录 `hvigorfile.ts` 的区别 | 文件 | 作用 | | ---------------------------------- | ---------------- | | `apps/harmony/hvigorfile.ts` | 定义整个 App 工程的构建任务 | | `apps/harmony/entry/hvigorfile.ts` | 定义 entry 模块的构建任务 | 可以这样理解： ```text 根 hvigorfile.ts：我是一个 App entry/hvigorfile.ts：我是 App 里的一个 HAP 模块 ``` --- ## 四、`apps/harmony/build-profile.json5` 这个是 **工程级构建配置文件**。 它通常负责： ```text 产品配置 签名配置 模块列表 构建目标 bundleName runtimeOS ``` 常见内容类似： ```json5 { app: { signingConfigs: [], products: [ { name: "default", signingConfig: "default" } ] }, modules: [ { name: "entry", srcPath: "./entry" } ] } ``` 它的重点是： ```text 整个 App 有哪些模块 使用哪个产品配置 使用哪个签名配置 ``` 你的命令里有： ```bash -p product=default ``` 这里的 `default` 就通常来自根目录 `build-profile.json5` 里的 `products` 配置。 --- ## 五、`apps/harmony/entry/build-profile.json5` 这个是 **entry 模块级构建配置文件**。 它负责 entry 模块自己的构建信息，例如： ```text 模块类型 编译目标 sourceOption buildOption targets ``` 常见内容类似： ```json5 { apiType: "stageMode", buildOption: {}, targets: [ { name: "default" } ] } ``` ### 和根目录 `build-profile.json5` 的区别 | 文件 | 作用 | | --------------------------- | ----------------- | | 根目录 `build-profile.json5` | 管整个 App 的产品、签名、模块 | | `entry/build-profile.json5` | 管 entry 模块自身怎么编译 | 可以这样理解： ```text 根 build-profile.json5：App 级别配置 entry/build-profile.json5：模块级别配置 ``` --- ## 六、`apps/harmony/oh-package.json5` 这个是 **工程级依赖配置文件**。 它类似前端项目里的： ```text package.json ``` 主要管理当前 HarmonyOS 工程需要的依赖。 比如： ```json5 { "devDependencies": { "@ohos/hvigor-ohos-plugin": "4.20.4" } } ``` 如果这里出现： ```json5 "@ohos/hvigor-ohos-arkui-x-plugin": "4.20.4" ``` 就说明工程依赖了 ArkUI-X 构建插件。 如果你不做跨端，这个依赖应该删除。 --- ## 七、`apps/harmony/entry/oh-package.json5` 这个是 **entry 模块自己的依赖配置文件**。 如果某个依赖只给 entry 模块使用，可以放这里。 例如： ```json5 { "dependencies": {} } ``` ### 和根目录 `oh-package.json5` 的区别 | 文件 | 作用 | | ------------------------ | -------------- | | 根目录 `oh-package.json5` | 工程级依赖，常放构建插件 | | `entry/oh-package.json5` | 模块级依赖，常放业务模块依赖 | 简单理解： ```text 根 oh-package.json5：构建工具、全局依赖 entry/oh-package.json5：entry 模块业务依赖 ``` --- ## 八、`apps/harmony/oh-package-lock.json5` 这个是 **依赖锁定文件**。 类似前端里的： ```text package-lock.json pnpm-lock.yaml yarn.lock ``` 它记录当前实际安装的依赖版本。 一般不手动改。 当你修改了： ```text oh-package.json5 ``` 再重新安装依赖后，这个文件会自动更新。 如果依赖状态混乱，可以删除后重新同步： ```bash rm -rf oh_modules oh-package-lock.json5 ``` 然后重新 Sync。 --- ## 九、`apps/harmony/hvigor/hvigor-config.json5` 这个文件是 **Hvigor 构建工具自身的配置**。 它不是业务配置，也不是 App 产品配置，而是控制 Hvigor 构建行为。 常见作用包括： ```text Hvigor 插件配置 构建缓存配置 任务执行配置 工具链相关配置 ``` 一般情况下不频繁修改。 如果项目突然引入了某些构建插件，也可以检查这个文件里有没有相关配置。 --- ## 十、`entry/src/main/module.json5` 这个文件非常重要，它是 **模块运行时配置文件**。 它描述 entry 模块的核心信息，比如： ```text 模块名称 入口 Ability 页面路由 权限声明 设备类型 metadata extensionAbility ``` 常见结构类似： ```json5 { module: { name: "entry", type: "entry", srcEntry: "./ets/Application/AbilityStage.ets", abilities: [ { name: "EntryAbility", srcEntry: "./ets/entryability/EntryAbility.ets", launchType: "singleton", startWindowIcon: "$media:startIcon", startWindowBackground: "$color:start_window_background" } ] } } ``` 这个文件和构建文件不同，它更接近： ```text 应用运行声明文件 ``` 比如你要加权限，通常也是改这里： ```json5 { module: { requestPermissions: [ { name: "ohos.permission.INTERNET" } ] } } ``` --- ## 十一、`AppScope/app.json5` 或 `app.json5` 这个是 **应用级运行配置**。 它通常描述整个 App 的基础信息，比如： ```text bundleName vendor versionCode versionName icon label ``` 常见结构类似： ```json5 { app: { bundleName: "com.example.demo", vendor: "example", versionCode: 1000000, versionName: "1.0.0", icon: "$media:app_icon", label: "$string:app_name" } } ``` ### 和 `module.json5` 的区别 | 文件 | 作用 | | -------------- | --------------- | | `app.json5` | 整个 App 的身份信息 | | `module.json5` | 某个模块的能力、页面、权限信息 | 可以这样理解： ```text app.json5：这个 App 是谁 module.json5：这个模块能做什么 ``` --- ## 十二、这些文件的关系总结 | 文件 | 层级 | 主要作用 | 是否经常修改 | | --------------------------- | ----- | ------------- | ------ | | `hvigorfile.ts` | 工程级 | 声明 App 构建任务 | 少 | | `entry/hvigorfile.ts` | 模块级 | 声明 HAP 模块构建任务 | 少 | | `build-profile.json5` | 工程级 | 产品、签名、模块配置 | 中 | | `entry/build-profile.json5` | 模块级 | entry 编译配置 | 少 | | `oh-package.json5` | 工程级 | 工程依赖、构建插件 | 中 | | `entry/oh-package.json5` | 模块级 | entry 模块依赖 | 中 | | `oh-package-lock.json5` | 工程级 | 锁定依赖版本 | 不手动改 | | `hvigor-config.json5` | 工具链级 | Hvigor 构建工具配置 | 少 | | `app.json5` | App 级 | App 身份信息 | 中 | | `module.json5` | 模块级 | Ability、页面、权限 | 较常改 | --- ## 十三、结合你这次的问题看 你这次报错的核心链路是： ```text 根目录 hvigorfile.ts ↓ 使用了 AppTasksForArkUIX ↓ Hvigor 认为这是 ArkUI-X 跨端工程 ↓ 开始查找 arkui-x.dir 或 ARKUIX_SDK_HOME ↓ 本机没装 ArkUI-X SDK ↓ 同步失败 ``` 你不要跨端，所以应该把工程级构建入口改回普通 HarmonyOS： ```ts export { appTasks } from '@ohos/hvigor-ohos-plugin'; ``` 同时检查依赖里是否还有： ```json5 "@ohos/hvigor-ohos-arkui-x-plugin" ``` 如果有，删除。 --- ## 十四、最简排查命令 在工程目录执行： ```bash grep -R "arkui-x\|ArkUIX\|hvigor-ohos-arkui-x-plugin" . ``` 如果还能搜到这些内容，说明项目里仍然存在 ArkUI-X 配置。 普通 HarmonyOS 项目里，核心应该是： ```ts export { appTasks } from '@ohos/hvigor-ohos-plugin'; ``` 和： ```ts export { hapTasks } from '@ohos/hvigor-ohos-plugin'; ``` 不应该再出现： ```ts AppTasksForArkUIX ``` 或： ```text @ohos/hvigor-ohos-arkui-x-plugin ``` ]]> http://herong.info/posts/harmonyos教程/HarmonyOS 应用签名体系：密钥、证书、Profile 与公钥指纹 http://herong.info/posts/harmonyos教程/HarmonyOS 应用签名体系：密钥、证书、Profile 与公钥指纹 Wed, 27 May 2026 00:00:00 GMT **私钥 = 你盖章用的章。 > 公钥 = 别人验证这个章是不是真的。** 华为文档里也明确说，密钥文件通常是 `.p12`，里面包含非对称加密用的公钥和私钥，用于数字签名和验证。([Huawei Developer][1]) --- ## 2. 密钥库：装“私章”的保险柜 **密钥库**通常就是你本地的 `.p12` 文件。 它不是单纯一个“密码”，而是一个文件，里面保存你的密钥信息，通常会有密码保护。 你可以理解为： ```txt 密钥库 .p12 = 保险柜 私钥 = 保险柜里的私章 密码 = 打开保险柜的钥匙 ``` 打包时 DevEco Studio 需要知道： ```txt 密钥库文件路径 密钥库密码 密钥别名 密钥密码 ``` 这些信息缺一个，签名就签不了。 最重要的是：**`.p12` 丢了很麻烦，泄露更严重。** 因为它控制你应用的签名身份。 --- ## 3. 证书：华为给你的“身份认证文件” 你自己生成密钥之后，还要向 AppGallery Connect 申请证书。 证书一般是 `.cer` 文件。 它的作用不是拿来签名，而是证明： ```txt 这个公钥/签名身份，是华为认可的某个开发者/应用使用的 ``` 你可以理解为： ```txt 私钥 = 你的私章 证书 = 权威机构给这个章开的证明 ``` 没有证书，系统或平台不知道这个签名身份是否合法。 鸿蒙调试、发布都会涉及证书。AppGallery Connect 里有调试证书、发布证书等管理入口。([Huawei Developer][2]) --- ## 4. Profile：应用的“通行证” **Profile 文件**通常是 `.p7b`。 它非常关键，但很多人容易把它和证书混在一起。 证书回答的是： ```txt 你是谁？ ``` Profile 回答的是： ```txt 你这个应用能不能跑？ 能在哪些设备上跑？ 用的是哪个包名？ 用了哪个证书？ 允许哪些权限？ ``` 华为文档里说，Profile 文件包含应用/元服务的包名、数字证书信息、允许申请的证书权限列表，以及允许调试的设备列表等信息。([Huawei Developer][3]) 所以人话就是： > **证书证明“签名身份是真的”； > Profile 证明“这个应用在这个场景下被允许运行”。** 调试版 Profile 通常会绑定调试设备。 发布版 Profile 用于正式上架。 --- ## 5. 公钥指纹：公钥的“身份证号码” **公钥指纹**通常是 SHA-256 指纹。 它不是公钥本身，而是从公钥/证书算出来的一串摘要。 类似： ```txt 公钥很长，不方便到处填 所以对它做 SHA-256 得到一串唯一性很强的指纹 ``` 你可以理解为： ```txt 公钥 = 一个人的完整身份资料 公钥指纹 = 这个人的身份证号 / 指纹编号 ``` 为什么要填公钥指纹？ 因为很多华为服务要确认： ```txt 当前调用我的这个应用，真的是你在 AppGallery Connect 里登记过的应用 ``` 比如 HMS Core、登录、推送、地图、支付、分享等服务，可能需要根据包名 + 签名指纹来识别应用身份。 AppGallery Connect 文档里也提到，可以添加 SHA-256 证书/公钥指纹，平台也可以根据签名证书计算 SHA-256 指纹。([Huawei Developer][4]) --- ## 6. 它们完整串起来是这样的 开发时大概流程是： ```txt 1. DevEco Studio 生成密钥库 .p12 ↓ 2. 根据密钥生成证书请求 CSR ↓ 3. 去 AppGallery Connect 申请证书 .cer ↓ 4. 用证书、包名、设备、权限等生成 Profile .p7b ↓ 5. 在 DevEco Studio 配置 .p12 + .cer + .p7b ↓ 6. 打包时用私钥签名 ↓ 7. 手机/系统/AppGallery 校验签名、证书、Profile ``` 官方文档也提到，构建应用需要用到密钥 `.p12`、证书 `.cer` 和 Profile `.p7b`，然后在 DevEco Studio 中配置签名信息。([Huawei Developer][5]) --- ## 7. 一张表说清楚 | 名称 | 文件后缀 | 人话理解 | 主要作用 | | ------- | ----------: | --------- | -------------- | | 密钥 | — | 私章/公章对 | 私钥签名，公钥验证 | | 密钥库 | `.p12` | 装私章的保险柜 | 保存私钥、公钥等签名材料 | | 证书 | `.cer` | 华为认可的身份证明 | 证明这个签名身份合法 | | Profile | `.p7b` | 应用通行证 | 绑定包名、证书、权限、设备等 | | 公钥指纹 | SHA-256 字符串 | 公钥的身份证号 | 给华为服务识别应用身份 | --- ## 8. Debug 和 Release 的区别 开发调试时一般用： ```txt Debug 证书 Debug Profile ``` 它通常会绑定调试设备，所以不是任何设备都能装。 正式发布时用： ```txt Release 证书 Release Profile ``` 这个用于上架和正式分发。 注意一个非常重要的点：**正式应用的签名不要随便换。**华为 FAQ 提到，HarmonyOS 应用目前不支持变更签名；如果密钥文件丢失，需要生成新密钥、重新申请发布证书和发布 Profile。([Huawei Developer][6]) 所以 `.p12` 一定要备份好。 --- ## 9. 最容易混淆的地方 你可以这样记： ```txt .p12：我用什么私钥签名？ .cer：华为怎么证明这个签名身份？ .p7b：这个应用被允许怎么运行？ SHA-256 指纹：华为服务怎么快速识别这个应用？ ``` 再简单一点： ```txt 密钥库 = 保险柜 私钥 = 盖章的章 证书 = 章的官方证明 Profile = 应用运行通行证 公钥指纹 = 这个章的唯一编号 ``` --- ## 10. 实际开发中你最该注意的 第一，`.p12` 和密码一定要保存好，最好进团队密码库或安全备份，不要只放某个人电脑上。 第二，Debug 和 Release 分开管理，不要拿调试签名去做正式包。 第三，接华为服务时，包名、签名证书、公钥指纹必须匹配，否则经常出现“本地能跑，服务调用失败”。 第四，换电脑、换同事、CI/CD 打包时，最容易缺的就是 `.p12`、密码、`.cer`、`.p7b` 这几样。 [1]: https://developer.huawei.com/consumer/cn/doc/hiai-Guides/signature-information-harmonyos-0000001246159273?utm_source=chatgpt.com "配置应用签名信息-开发准备-HarmonyOS-机器学习服务" [2]: https://developer.huawei.com/consumer/en/doc/app/agc-help-add-debugcert-0000001914263178?utm_source=chatgpt.com "Requesting a Debug Certificate-Debugging Your App ..." [3]: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-signing?utm_source=chatgpt.com "配置调试签名" [4]: https://developer.huawei.com/consumer/cn/doc/app/agc-help-signature-info-0000001628566748?utm_source=chatgpt.com "(可选）配置应用签名证书指纹-开发应用-AppGallery Connect ..." [5]: https://developer.huawei.com/consumer/cn/doc/hmscore-common-Guides/harmony-signature-info-0000001167185654?utm_source=chatgpt.com "配置应用签名信息-将HMS Core添加至HarmonyOS应用" [6]: https://developer.huawei.com/consumer/en/doc/app/agc-help-releasefaq-0000001110342644?utm_source=chatgpt.com "FAQs-Releasing an App-AppGallery Connect Help Center" ]]> http://herong.info/posts/harmonyos教程/README http://herong.info/posts/harmonyos教程/README Mon, 27 Jan 2025 00:00:00 GMT 基于 ArkTS 和 ArkUI 的 HarmonyOS 应用开发系统教程，从基础到进阶，涵盖 UI 组件、状态管理、性能优化等核心内容。 ## 📚 教程目录 ### 第一部分：UI 组件与样式 构建美观、高效的用户界面。 - [图标方案选型与实战：SVG/IconFont/Emoji 完整对比](./UI组件与样式/图标方案选型与实战：SVG-IconFont-Emoji完整对比.md) ⭐ - [SVG 图标获取与使用实战：从下载到代码落地](./UI组件与样式/SVG图标获取与使用实战：从下载到代码落地.md) ⭐ - [快速获取常用功能图标：聊天/录音/用户/设置](./UI组件与样式/快速获取常用功能图标：聊天-录音-用户-设置.md) ⭐ ### 第二部分：布局与适配 （待补充） ### 第三部分：状态管理 （待补充） ### 第四部分：网络与数据 （待补充） ### 第五部分：性能优化 （待补充） ### 第六部分：系统能力 访问 HarmonyOS 系统底层能力和原生模块开发。 - [NAPI 原生模块接口入门指南](./系统能力/NAPI-原生模块接口入门指南.md) ⭐ ### 第七部分：测试与调试 （待补充） ### 第八部分：发布与运营 （待补充） --- ## 🎯 学习路线 ### 初学者路线 ```text 1. UI 组件与样式 ├─ 图标方案选型 ← 理论对比 ├─ SVG 图标实战 ← 完整流程 └─ 快速获取图标 ← 即用方案 2. 布局与适配 └─ （待补充） 3. 状态管理 └─ （待补充） ``` ### 进阶开发者路线 ```text 1. 性能优化 2. 系统能力 ├─ NAPI 原生模块接口 ← 高性能计算 3. 测试与调试 ``` --- ## 💡 特色内容 ### ⭐ 图标方案选型与实战 **核心内容：** - SVG + Image 组件（推荐） - IconFont 自定义字体 - Emoji 快速原型 - 模板渲染与主题化 - 完整实战示例 **适合人群：** - 需要实现图标系统的开发者 - 需要主题切换功能的项目 - 希望统一 UI 风格的团队 **学习收获：** - 掌握三种图标方案的优劣 - 学会 SVG 模板渲染与着色 - 实现主题化图标系统 - 了解性能优化技巧 ### ⭐ SVG 图标获取与使用实战 **核心内容：** - 图标资源获取（Iconify、Material Symbols、Remix Icon） - SVG 优化处理（SVGOMG 工具） - 资源目录结构与命名规范 - 完整代码改造示例 - 4 个可直接使用的 SVG 文件 **适合人群：** - 想快速上手 SVG 图标的开发者 - 需要完整落地流程的初学者 - 正在从 Emoji 迁移到 SVG 的项目 **学习收获：** - 从 0 到 1 实现 SVG 图标系统 - 掌握 SVG 优化与处理技巧 - 学会资源管理与命名规范 - 解决常见问题与陷阱 ### ⭐ 快速获取常用功能图标 **核心内容：** - 3 大图标源入口（Material Symbols、Remix Icon、Iconify） - 4 个常用功能图标推荐名称对照表 - 快速下载步骤（聊天/录音/用户/设置） - 完整迁移指南（Emoji → SVG） - 主题色管理与夜间模式 **适合人群：** - 需要快速找到特定图标的开发者 - 不知道图标英文名称的初学者 - 想批量下载常用图标的项目 **学习收获：** - 快速查找和下载所需图标 - 掌握图标命名对照技巧 - 3 步完成 Emoji 到 SVG 迁移 - 实现主题化图标系统 ### ⭐ NAPI 原生模块接口入门指南 **核心内容：** - NAPI 基础概念与核心价值 - 开发环境搭建与项目结构 - 快速开始：创建第一个 NAPI 模块 - 常用 API：数据类型转换、对象操作、数组操作 - 实战案例：图像处理、AI 推理 - 注意事项：内存管理、异常处理、线程安全 - 进阶主题：异步操作、回调函数 **适合人群：** - 需要高性能计算的开发者 - 需要访问系统底层能力的项目 - 想复用现有 C/C++ 库的团队 - 进行 AI 推理、图像处理等场景 **学习收获：** - 掌握 NAPI 开发流程 - 学会 JavaScript 与 C/C++ 互操作 - 实现高性能原生模块 - 集成第三方 C/C++ 库 --- ## 📖 使用指南 ### 如何阅读本教程 1. **按需学习**：根据目录选择需要的章节 2. **动手实践**：每篇文章都有完整代码示例 3. **循序渐进**：建议按照学习路线顺序学习 4. **查漏补缺**：可作为速查手册使用 ### 代码示例说明 ```typescript // ⭐ 推荐做法 Image($r("app.media.icon_home")) .renderMode(ImageRenderMode.Template) .fillColor("#4A90E2"); // ⚠️ 注意事项 // 未设置 renderMode 时，fillColor 不生效 // ❌ 不推荐 Text("💬"); // Emoji 跨设备不一致 ``` --- ## 🔧 开发环境 ### 推荐配置 - **IDE**：DevEco Studio 4.0+ - **SDK**：HarmonyOS 4.0+ - **语言**：ArkTS (TypeScript) - **UI 框架**：ArkUI ### 快速搭建 1. 下载 [DevEco Studio](https://developer.huawei.com/consumer/cn/deveco-studio/) 2. 安装 HarmonyOS SDK 3. 创建第一个 ArkTS 项目 4. 运行示例代码 --- ## 📝 更新日志 - **2025-01-27**：创建教程目录结构 - **2025-01-27**：添加图标方案选型与实战章节 - **2025-01-27**：添加 SVG 图标获取与使用实战章节 - **2025-01-27**：添加快速获取常用功能图标章节 - **2025-01-27**：添加 NAPI 原生模块接口入门指南章节 --- ## 🤝 贡献指南 欢迎贡献内容！ ### 贡献方式 - 提交 Issue 反馈问题 - 提交 Pull Request 改进内容 - 分享学习心得 ### 内容规范 - 代码示例完整可运行 - 配图清晰易懂 - 注释详细规范 - 排版美观统一 --- ## 🔗 相关资源 ### 官方文档 - [HarmonyOS 开发者官网](https://developer.huawei.com/consumer/cn/harmonyos/) - [ArkTS 语言规范](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/arkts-get-started-V13) - [ArkUI 组件库](https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V13/arkui-ts-components-V13) ### 学习资源 - [HarmonyOS 示例代码](https://gitee.com/openharmony) - [开发者社区](https://developer.huawei.com/consumer/cn/forum/) - [OpenHarmony 文档](https://docs.openharmony.cn/) ### 工具推荐 - [iconfont 图标库](https://www.iconfont.cn/) - [iconify 图标集合](https://iconify.design/) - [ColorSpace 配色工具](https://mycolor.space/) --- ## 📧 联系方式 - **技术分享**：[herong.info](https://herong.info) - **问题反馈**：通过 Issue 或评论区 --- **让我们一起打造更好的 HarmonyOS 应用！** 🚀 ]]> http://herong.info/posts/java快速入门/0-提示词 http://herong.info/posts/java快速入门/0-提示词 Tue, 19 May 2026 00:00:00 GMT Service -> Mapper -> database。 5. 给出一个最小可运行示例或接口请求。 6. 给出验证方式：命令、预期输出、测试用例或错误复盘。 7. 标出常见坑，尤其是空值、类型转换、异常、SQL 参数、线程安全和版本差异。 代码： （粘贴代码） ``` ## 回答风格约定 - **自动识别归类**：多个知识点时分条归类 - **结构化**：适用场景 → 放入章节 → 调用链 → 核心代码 → 验证方式 → 常见坑 - **可运行**：示例尽量完整；普通 Java 示例保持 Java 17+ 可运行，新机器优先使用 LTS 版本 - **速成友好**：表格、列表优先，理论点到为止 - **不伪造结果**：没有运行过命令时，明确写“预期输出”，不要写成真实运行结果 --- 回到 [Java 快速入门教程](./README.md) ::: ]]> http://herong.info/posts/java快速入门/01-课程路线图 http://herong.info/posts/java快速入门/01-课程路线图 Fri, 03 Jul 2026 00:00:00 GMT http://herong.info/posts/java快速入门/02-当前实践说明 http://herong.info/posts/java快速入门/02-当前实践说明 Fri, 03 Jul 2026 00:00:00 GMT http://herong.info/posts/java快速入门/03-学习验收清单 http://herong.info/posts/java快速入门/03-学习验收清单 Fri, 03 Jul 2026 00:00:00 GMT Service -> Model` 调用链 | | 核心 API | 文件读取和集合统计练习 | 能处理空文件、非法行、重复数据 | | Maven | 标准 Maven 项目 | `mvn test` 能重复通过 | | Spring Boot | 任务 API | `curl` 或接口工具能完成增查改 | | 数据库 | 持久化任务表 | 能说明请求参数如何进入 SQL | | 工程质量 | 测试、异常、日志 | 至少覆盖 3 个失败用例 | ## 学习日志模板 把下面内容追加到 `~/java-quickstart-course/learning-log.md`。 ```md ## YYYY-MM-DD 阶段名称 练习目标： 运行命令： 预期结果： 实际结果： 生成或修改的文件： 遇到的错误： 定位过程： 最终修复： 我现在能解释： 下一步： ``` ## Demo 用例 ### Demo 1：基础语法 输入：`[98, 76, 59, 88, 100]` 预期： - 最高分是 `100`。 - 最低分是 `59`。 - 平均分能解释小数处理方式。 - 不及格人数是 `1`。 判断重点： - 是否正确使用循环和条件。 - 是否处理整数除法。 - 是否把计算逻辑拆成方法。 ### Demo 2：集合和文件 输入文件： ```text 1,learn-java,TODO 2,write-api,DONE 3,fix-test,TODO bad-line ``` 预期： - `TODO` 数量是 `2`。 - `DONE` 数量是 `1`。 - 非法行被记录为错误，不中断整个程序。 判断重点： - 是否选择合适的集合结构。 - 是否区分正常数据和错误数据。 - 是否知道输出文件或日志在哪里。 ### Demo 3：Spring Boot API 请求： ```bash curl -X POST http://localhost:8080/tasks \ -H 'Content-Type: application/json' \ -d '{"title":"learn-java","status":"TODO"}' ``` 预期： - 返回成功状态。 - 响应体包含任务 id、标题、状态和创建时间。 - 服务器日志能看到请求进入 Controller。 判断重点： - Controller 是否只处理 HTTP。 - Service 是否处理业务规则。 - Repository 或 Mapper 是否只处理数据访问。 ## 失败用例 | 用例 | 预期行为 | |------|----------| | 缺少任务标题 | 返回清晰的参数错误，不写入数据库 | | 查询不存在的任务 id | 返回统一错误结构，不暴露数据库细节 | | 状态值非法 | 返回可读错误信息，并说明允许的状态 | | 数据库连接失败 | 日志能定位配置或服务不可用 | | 测试失败 | 能通过失败断言找到行为变化 | ## 评分规则 | 分数 | 表现 | |------|------| | 1 | 只能照抄代码，不能独立运行 | | 2 | 能跑通，但解释不清楚调用链和边界 | | 3 | 能完成最小功能，能定位常见错误 | | 4 | 能补测试、处理失败用例，并说明设计取舍 | | 5 | 能把同一结构迁移到新需求，例如文件上传、分页查询或权限校验 | ## 毕业标准 你可以结束第一轮学习，如果同时满足： - 从空目录创建并运行一个 Maven 或 Spring Boot 项目。 - 写出至少 4 个接口或命令行功能。 - 保留至少 5 个测试或验收请求。 - 复盘至少 3 个真实错误。 - 能讲清楚 Controller、Service、Mapper、DO、DTO、VO、配置文件和测试分别负责什么。 - 能指出旧笔记中的一个过时方案，并说明新项目里会如何重新选择。 回到 [Java 快速入门教程](./README.md)。 ::: ]]> http://herong.info/posts/java快速入门/README http://herong.info/posts/java快速入门/README Fri, 03 Jul 2026 00:00:00 GMT http://herong.info/posts/java快速入门/为什么要重新系统学习 Java http://herong.info/posts/java快速入门/为什么要重新系统学习 Java Tue, 19 May 2026 00:00:00 GMT http://herong.info/posts/kotlin快速入门/Kotlin + Swift 快速入门实战课程大纲（AI 驱动版） http://herong.info/posts/kotlin快速入门/Kotlin + Swift 快速入门实战课程大纲（AI 驱动版） Fri, 12 Sep 2025 00:00:00 GMT http://herong.info/posts/kotlin快速入门/为什么要学 Kotlin 和 Swift：AI 时代的移动开发学习法 http://herong.info/posts/kotlin快速入门/为什么要学 Kotlin 和 Swift：AI 时代的移动开发学习法 Fri, 12 Sep 2025 00:00:00 GMT http://herong.info/posts/rust/rust-advanced http://herong.info/posts/rust/rust-advanced Mon, 01 Jan 2024 00:00:00 GMT 本文是 Rust 系列教程的第二篇，深入讲解模块系统、特征、并发编程等进阶主题。 ## 1. 模块系统 ### 1.1 模块定义 ```rust // src/lib.rs 或 main.rs mod front_of_house { // 模块内容 pub fn add() {} } mod back_of_house { // 私有模块 } ``` ### 1.2 模块的可见性 ```rust mod restaurant { pub struct Breakfast { pub toast: String, // 公开字段 seasonal_fruit: String, // 私有字段 } impl Breakfast { pub fn summer(toast: String) -> Breakfast { Breakfast { toast, seasonal_fruit: String::from("peaches"), } } } } ``` ### 1.3 use 关键字 ```rust // 使用绝对路径 use std::collections::HashMap; // 使用相对路径 use crate::front_of_house::hosting; // 重命名 use std::io::{self, Read}; // self 表示 io 本身 // 导入所有公开项（不推荐） use std::collections::*; // 使用 as 别名 use std::io::Result as IoResult; ``` ### 1.4 分离文件到模块 **项目结构：** ``` src/ ├── main.rs ├── lib.rs ├── front_of_house.rs └── front_of_house/ └── hosting.rs ``` **src/main.rs:** ```rust mod front_of_house; use front_of_house::hosting; fn main() { hosting::add_to_waitlist(); } ``` **src/front_of_house.rs:** ```rust pub mod hosting; ``` **src/front_of_house/hosting.rs:** ```rust pub fn add_to_waitlist() {} ``` ## 2. 特征（Trait） ### 2.1 定义特征 ```rust trait Summary { fn summarize(&self) -> String; } ``` ### 2.2 为类型实现特征 ```rust struct Article { headline: String, author: String, } impl Summary for Article { fn summarize(&self) -> String { format!("{}, by {}", self.headline, self.author) } } ``` ### 2.3 默认实现 ```rust trait Summary { fn summarize(&self) -> String { String::from("(Read more...)") } fn summarize_author(&self) -> String { format!("(Read more from {}...)", self.author()) } fn author(&self) -> String; // 必需方法 } ``` ### 2.4 特征作为参数 ```rust // impl Trait 语法 fn notify(item: impl Summary) { println!("Breaking news! {}", item.summarize()); } // Trait Bound 语法 fn notify(item: T) { println!("Breaking news! {}", item.summarize()); } // 多个特征约束 fn notify(item: impl Summary + Display) {} // 使用 where 从句（更清晰） fn some_function(t: T, u: U) -> i32 where T: Display + Clone, U: Clone + Debug, { // ... } ``` ### 2.5 特征作为返回值 ```rust fn returns_summarizable() -> impl Summary { Article { headline: String::from("Breaking news!"), author: String::from("John Doe"), } } ``` ### 2.6 派生特征（Derive） ```rust #[derive(Debug, Clone, Copy)] struct Point { x: i32, y: i32, } // 常见的可派生特征 // Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash ``` ## 3. 生命周期 ### 3.1 生命周期注解 ```rust // 单个生命周期参数 fn longest<'a>(x: &'a str, y: &'a str) -> &'a str { if x.len() > y.len() { x } else { y } } ``` ### 3.2 结构体中的生命周期 ```rust struct ImportantExcerpt<'a> { part: &'a str, } impl<'a> ImportantExcerpt<'a> { fn level(&self) -> i32 { 3 } fn announce_and_return_part(&self, announcement: &str) -> &str { println!("Attention please: {}", announcement); self.part } } ``` ### 3.3 生命周期省略规则 编译器会自动推断以下情况的生命周期： 1. 函数参数的生命周期（输入生命周期） 2. 输出生命周期（如果有唯一引用） 3. `&self` 的生命周期被赋给所有输出生命周期参数 ### 3.4 静态生命周期 ```rust let s: &'static str = "I have a static lifetime."; ``` ## 4. 泛型 ### 4.1 泛型函数 ```rust fn largest(list: &[T]) -> T { let mut largest = list[0]; for &item in list { if item > largest { largest = item; } } largest } ``` ### 4.2 泛型结构体 ```rust struct Point { x: T, y: T, } let integer = Point { x: 5, y: 10 }; let float = Point { x: 1.0, y: 4.0 }; ``` ### 4.3 泛型枚举 ```rust enum Option { Some(T), None, } enum Result { Ok(T), Err(E), } ``` ### 4.4 泛型方法 ```rust impl Point { fn x(&self) -> &T { &self.x } } impl Point { fn distance_from_origin(&self) -> f32 { (self.x.powi(2) + self.y.powi(2)).sqrt() } } ``` ## 5. 智能指针 ### 5.1 Box ```rust let b = Box::new(5); println!("b = {}", b); // 递归数据结构 enum List { Cons(i32, Box), Nil, } ``` ### 5.2 Rc - 引用计数 ```rust use std::rc::Rc; let a = Rc::new(5); let b = Rc::clone(&a); let c = Rc::clone(&a); println!("count = {}", Rc::strong_count(&a)); ``` ### 5.3 RefCell - 内部可变性 ```rust use std::cell::RefCell; let value = RefCell::new(5); { let mut r1 = value.borrow_mut(); *r1 += 1; } println!("{}", value.borrow()); ``` ### 5.4 Arc - 原子引用计数 ```rust use std::sync::Arc; use std::thread; let data = Arc::new(vec![1, 2, 3]); for i in 0..3 { let data = Arc::clone(&data); thread::spawn(move || { println!("{:?}", data); }); } ``` ## 6. 并发编程 ### 6.1 线程 ```rust use std::thread; use std::time::Duration; let handle = thread::spawn(|| { for i in 1..10 { println!("hi number {} from spawned thread!", i); thread::sleep(Duration::from_millis(1)); } }); for i in 1..5 { println!("hi number {} from main thread!", i); thread::sleep(Duration::from_millis(1)); } handle.join().unwrap(); ``` ### 6.2 使用 move 闭包 ```rust let v = vec![1, 2, 3]; let handle = thread::spawn(move || { println!("Here's a vector: {:?}", v); }); // v 不再可用，所有权已转移到线程 // println!("{:?}", v); // 错误！ handle.join().unwrap(); ``` ### 6.3 通道 ```rust use std::sync::mpsc; use std::thread; let (tx, rx) = mpsc::channel(); thread::spawn(move || { let val = String::from("hi"); tx.send(val).unwrap(); }); let received = rx.recv().unwrap(); println!("Got: {}", received); ``` ### 6.4 多个发送者 ```rust let (tx, rx) = mpsc::channel(); let tx1 = tx.clone(); thread::spawn(move || { let vals = vec![ String::from("hi"), String::from("from"), String::from("the"), String::from("thread"), ]; for val in vals { tx1.send(val).unwrap(); thread::sleep(Duration::from_millis(1)); } }); thread::spawn(move || { let vals = vec![ String::from("more"), String::from("messages"), ]; for val in vals { tx.send(val).unwrap(); thread::sleep(Duration::from_millis(1)); } }); for received in rx { println!("Got: {}", received); } ``` ### 6.5 共享状态并发 ```rust use std::sync::{Arc, Mutex}; use std::thread; let counter = Arc::new(Mutex::new(0)); let mut handles = vec![]; for _ in 0..10 { let counter = Arc::clone(&counter); let handle = thread::spawn(move || { let mut num = counter.lock().unwrap(); *num += 1; }); handles.push(handle); } for handle in handles { handle.join().unwrap(); } println!("Result: {}", *counter.lock().unwrap()); ``` ### 6.6 使用 parking_lot（更高效） ```rust use parking_lot::Mutex; let data = Arc::new(Mutex::new(0)); let data_clone = Arc::clone(&data); thread::spawn(move || { let mut num = data_clone.lock(); *num += 1; }); ``` ## 7. 异步编程 ### 7.1 Future ```rust use std::future::Future; fn async_function() -> impl Future

{ async { 42 } } ``` ### 7.2 async/await ```rust async fn learn_song() -> &'static str { "song" } async fn sing_song(song: &str) { println!("Singing: {}", song); } async fn dance() { println!("Dancing!"); } async fn learn_and_sing() { let song = learn_song().await; sing_song(song).await; } async fn async_main() { let f1 = learn_and_sing(); let f2 = dance(); futures::join!(f1, f2); } ``` ### 7.3 使用 tokio ```rust use tokio::time::{sleep, Duration}; async fn async_function() { println!("Async function started"); sleep(Duration::from_secs(1)).await; println!("Async function completed"); } #[tokio::main] async fn main() { async_function().await; } ``` ## 练习 1. 创建一个自定义的 `Error` 类型，并实现 `std::error::Error` 特征 2. 实现一个线程池，能够并发执行多个任务 3. 创建一个 `Cache` 结构体，使用 `RefCell` 实现内部可变性 4. 使用 `Arc` 和 `Mutex` 实现一个线程安全的计数器 --- 上一篇：[Rust 入门基础教程（一）：语法基础](./rust-basics.md) 下一篇：[Rust 实战教程（三）：项目实战](./rust-practical.md) ]]>

http://herong.info/posts/rust/rust-basics http://herong.info/posts/rust/rust-basics Mon, 01 Jan 2024 00:00:00 GMT 本文是 Rust 系列教程的第一篇，适合有编程基础但从未接触过 Rust 的开发者。我们将从最基础的语法开始，通过实际代码示例学习。 ## 1. Hello World 与 Cargo ### 1.1 第一个程序 ```rust fn main() { println!("Hello, Rust!"); } ``` **关键点：** - `fn` 是函数关键字 - `main` 是程序入口点 - `println!` 是宏（注意感叹号） - 每行以分号结尾 ### 1.2 Cargo 项目管理 Rust 使用 **Cargo** 管理项目，类似 npm： ```bash cargo new my_project cd my_project cargo run ``` **Cargo.toml** 配置文件： ```toml [package] name = "my_project" version = "0.1.0" edition = "2021" [dependencies] serde = "1.0" ``` ## 2. 变量和数据类型 ### 2.1 基本类型 ```rust // 整数类型 let age: u32 = 30; // 无符号 32 位 let count: i32 = -5; // 有符号 32 位 // 浮点数 let price: f64 = 99.99; // 布尔值 let is_active: bool = true; // 字符（4字节，支持 Unicode） let ch: char = '中'; ``` ### 2.2 变量可变性 **Rust 变量默认不可变：** ```rust let x = 5; x = 10; // ❌ 编译错误！ let mut y = 5; y = 10; // ✅ 正确 ``` ### 2.3 数组和 Vector ```rust // 固定大小数组 let arr: [i32; 3] = [1, 2, 3]; let first = arr[0]; // 动态数组 Vec（最常用） let mut vec = Vec::new(); vec.push(1); // 或使用宏 let vec2 = vec![1, 2, 3, 4, 5]; ``` ### 2.4 字符串 ```rust // &str: 字符串切片（不可变） let s1: &str = "Hello"; // String: 可变字符串 let mut s2 = String::from("Hello"); s2.push_str(" World"); // 转换 let s3 = "hello".to_string(); ``` ## 3. 控制流 ### 3.1 if/else ```rust let age = 18; if age >= 18 { println!("成年人"); } else { println!("未成年人"); } // if 是表达式，可以返回值 let status = if age >= 18 { "成年" } else { "未成年" }; ``` ### 3.2 循环 ```rust // loop 无限循环 loop { println!("无限循环"); break; } // while 循环 let mut i = 0; while i < 10 { i += 1; } // for 循环（最常用） for i in 0..10 { println!("{}", i); } // 遍历数组 let numbers = vec![1, 2, 3]; for num in numbers { println!("{}", num); } ``` ### 3.3 match 表达式 ```rust let result = Some(5); match result { Some(x) => println!("Got: {}", x), None => println!("No value"), } // 枚举匹配 enum Status { Pending, Completed, Failed, } match status { Status::Pending => println!("等待中"), Status::Completed => println!("已完成"), Status::Failed => println!("失败"), } ``` ## 4. 函数 ```rust // 基本函数 fn greet(name: &str) { println!("Hello, {}!", name); } // 带返回值 fn add(a: i32, b: i32) -> i32 { a + b // 最后一行表达式的值（无分号） } // 显式 return fn max(a: i32, b: i32) -> i32 { if a > b { return a; } b } ``` ## 5. 所有权系统（核心概念） ### 5.1 所有权规则 1. 每个值有唯一的所有者 2. 同时只能有一个所有者 3. 所有者离开作用域，值被销毁 ```rust let s1 = String::from("hello"); let s2 = s1; // s1 的所有权移给 s2 // println!("{}", s1); // ❌ s1 已失效 println!("{}", s2); // ✅ 正确 ``` ### 5.2 引用和借用 ```rust // 不可变引用（可以有多个） let s = String::from("hello"); let r1 = &s; let r2 = &s; // ✅ 可以有多个不可变引用 // 可变引用（只能有一个） let mut s = String::from("hello"); let r1 = &mut s; // let r2 = &mut s; // ❌ 错误！ ``` ## 6. 结构体和枚举 ### 6.1 结构体 ```rust struct Person { name: String, age: u32, } let person = Person { name: String::from("Alice"), age: 30, }; println!("{}: {}", person.name, person.age); ``` ### 6.2 方法 ```rust impl Person { // 关联函数（类似静态方法） fn new(name: String, age: u32) -> Self { Self { name, age } } // 方法 fn greet(&self) { println!("Hello, I'm {}", self.name); } } let alice = Person::new("Alice".to_string(), 30); alice.greet(); ``` ### 6.3 枚举 ```rust enum Direction { Up, Down, Left, Right, } // 带数据的枚举 enum Message { Quit, Move { x: i32, y: i32 }, Write(String), } // 使用 match let msg = Message::Move { x: 10, y: 20 }; match msg { Message::Quit => println!("退出"), Message::Move { x, y } => println!("移动到 ({}, {})", x, y), Message::Write(text) => println!("消息: {}", text), _ => println!("其他"), } ``` ## 7. 错误处理 ### 7.1 Result 类型 ```rust fn divide(a: f64, b: f64) -> Result { if b == 0.0 { Err("Cannot divide by zero".to_string()) } else { Ok(a / b) } } // 处理 Result match divide(10.0, 2.0) { Ok(result) => println!("结果: {}", result), Err(e) => println!("错误: {}", e), } ``` ### 7.2 Option 类型 ```rust // Option 表示可能有值 let numbers = vec![1, 2, 3]; let first = numbers.first(); // Option<&i32> match first { Some(value) => println!("第一个: {}", value), None => println!("没有元素"), } // 安全的 unwrap let value = first.unwrap_or(&0); ``` ### 7.3 ? 运算符 ```rust fn read_file() -> Result { let contents = std::fs::read_to_string("file.txt")?; Ok(contents) } // ? 遇到错误自动返回 ``` ## 练习 尝试实现以下功能： 1. 写一个函数，计算阶乘 2. 定义一个 `Rectangle` 结构体，包含宽度和高度，并实现计算面积的方法 3. 写一个函数，接受一个整数切片，返回最大值（使用 `Option`） 4. 实现一个简单的计算器，支持加减乘除 --- 下一篇：[Rust 入门进阶教程（二）：模块、特征和并发](./rust-advanced.md) ]]> http://herong.info/posts/rust/rust-practical http://herong.info/posts/rust/rust-practical Mon, 01 Jan 2024 00:00:00 GMT 本文结合实际项目代码，深入讲解 Rust 的高级特性、FFI、宏编程等实战应用。 ## 1. 项目代码中的核心概念解析 ### 1.1 N-API 集成 你的代码使用 `#[napi]` 宏将 Rust 函数导出给 Node.js： ```rust use napi_derive::napi; #[napi] pub fn init(surface_id: String, width: u32, height: u32, _opts: InitOptions) -> Result<()> { // 函数实现 } ``` **要点解析：** - `#[napi]` 是过程宏，用于自动生成 FFI 绑定代码 - `Result<()>` 表示可能失败的函数（无返回值） - Rust 的类型自动映射到 JavaScript 类型 ### 1.2 结构体与 N-API ```rust #[napi(object)] pub struct InitOptions { pub age: u32, pub life: u32, } ``` **关键点：** - `#[napi(object)]` 将结构体映射为 JavaScript 对象 - `pub` 字段会被导出到 JavaScript - 类型映射：`u32` → JavaScript `number` ### 1.3 静态可变变量 ```rust static mut R: Option = None; ``` **问题与解决方案：** - `static mut` 是全局可变状态，不安全 - 必须用 `unsafe` 块访问 - 更好的做法是使用 `Mutex` 或 `Arc>` ```rust // 更好的实现 use std::sync::Mutex; static R: Mutex> = Mutex::new(None); // 使用 let mut r = R.lock().unwrap(); if let Some(renderer) = r.as_mut() { // ... } ``` ### 1.4 错误处理模式 ```rust pub fn new(surface_id: String, width: u32, height: u32) -> napi::Result { unsafe { let display = eglGetDisplay(EGL_DEFAULT_DISPLAY); if display == EGL_NO_DISPLAY { return Err(napi::Error::from_reason("eglGetDisplay failed")); } // ... Ok(Self { /* ... */ }) } } ``` **模式分析：** - 使用 `Result` 进行错误传播 - `Err()` 返回错误，`Ok()` 返回成功值 - 错误信息会传递到 JavaScript ## 2. 外部函数接口（FFI） ### 2.1 C 函数声明 ```rust extern "C" { fn eglGetDisplay(native_display: *mut c_void) -> EGLDisplay; fn eglInitialize(dpy: EGLDisplay, major: *mut i32, minor: *mut i32) -> i32; } ``` **关键概念：** 1. **`extern "C"`** - 指定 C 调用约定 2. **裸指针** - `*mut c_void` 是可变裸指针 3. **类型别名** - `type EGLDisplay = *mut c_void;` ### 2.2 指针类型 ```rust // 不同类型指针示例 let raw_ptr: *const i32 = &x as *const i32; // 不可变裸指针 let mut_ptr: *mut i32 = &mut x as *mut i32; // 可变裸指针 let ref_: &i32 = &x; // 引用（安全） // 解引用（需要 unsafe） unsafe { let value = *raw_ptr; } ``` ### 2.3 原始类型转换 ```rust #[repr(C)] // C 兼容的内存布局 struct Point { x: f32, y: f32, } let bytes = std::mem::size_of::(); let byte_slice: &[u8] = unsafe { std::slice::from_raw_parts( point as *const Point as *const u8, bytes ) }; ``` ## 3. 内存管理和 RAII ### 3.1 Drop Trait 你的代码实现了 `Drop` 来清理资源： ```rust impl Drop for GLRenderer { fn drop(&mut self) { unsafe { eglMakeCurrent(self.display, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT); // 删除所有 GL 资源 if let Some(v) = self.vao_future { self.gl.delete_vertex_array(v); } // ... } } } ``` **RAII（Resource Acquisition Is Initialization）模式：** - 资源在对象创建时获取 - 在对象销毁时自动释放 - 无需手动管理内存 ### 3.2 实例化渲染 ```rust // 使用 Vec 动态分配 let mut future = Vec::new(); for _yi in (current_index + 1)..life_years { if let Some((c, r)) = free.first().cloned() { future.push(Instance { pos: to_world(c, r), color: color_future, }); free.remove(0); } } ``` **内存管理要点：** - `Vec` 会自动增长和缩小 - 超出作用域时自动释放 - 无需手动 `free` 或 `delete` ## 4. 迭代器和函数式编程 ### 4.1 map 和 collect ```rust let raw: Vec = instances.iter() .map(|it| RawInst { pos: it.pos, color: it.color }) .collect(); ``` **步骤分解：** 1. `instances.iter()` - 创建迭代器 2. `.map(|it| ...)` - 转换每个元素 3. `.collect()` - 收集到 Vec **等价的循环写法：** ```rust let mut raw = Vec::new(); for it in instances.iter() { raw.push(RawInst { pos: it.pos, color: it.color }); } ``` ### 4.2 更多迭代器方法 ```rust // filter - 过滤 let evens: Vec = numbers.iter() .filter(|&&x| x % 2 == 0) .collect(); // fold - 累积 let sum = numbers.iter() .fold(0, |acc, x| acc + x); // enumerate - 带索引 for (i, item) in vec.iter().enumerate() { println!("{}: {}", i, item); } ``` ### 4.3 链式调用 ```rust let result = data.iter() .filter(|x| x > &&0) .map(|x| x * 2) .take(10) .collect::>(); ``` ## 5. 闭包（Closures） ### 5.1 闭包示例 ```rust let multiplier = 2; let closure = |x| x * multiplier; // 使用 let result = closure(5); // 10 ``` ### 5.2 闭包捕获 ```rust // 移动捕获 let data = vec![1, 2, 3]; let closure = move || { println!("{:?}", data); // data 的所有权移入闭包 }; // 可变捕获 let mut counter = 0; let mut closure = || { counter += 1; }; ``` ### 5.3 函数指针与闭包 ```rust fn apply(f: F) -> i32 where F: FnOnce() -> i32, { f() } let closure = || 42; let result = apply(closure); ``` ## 6. 宏编程 ### 6.1 派生宏（Derive） ```rust #[derive(Clone, Copy, Debug, Serialize, Deserialize)] pub struct Instance { pub pos: [f32; 3], pub color: [f32; 4], } ``` **可派生特征：** - `Clone` - 克隆对象 - `Copy` - 拷贝语义（栈上复制） - `Debug` - 格式化输出 - `Serialize/Deserialize` - 序列化 ### 6.2 属性宏 ```rust #[napi] pub fn init() -> Result<()> { } // 展开后生成： extern "C" fn init_binding(env: napi::Env, ...) -> napi::Value { // 自动生成的绑定代码 } ``` ### 6.3 声明宏 ```rust macro_rules! my_vec { ($($x:expr),*) => { { let mut temp_vec = Vec::new(); $( temp_vec.push($x); )* temp_vec } }; } // 使用 let v = my_vec!(1, 2, 3); ``` ## 7. 并发模式 ### 7.1 懒加载（Lazy Static） ```rust use once_cell::sync::Lazy; static RUNNING: Lazy> = Lazy::new(|| Mutex::new(false)); // 使用 *RUNNING.lock().unwrap() = true; ``` **为什么需要 `Lazy`？** - 静态变量初始化必须是常量表达式 - `Lazy::new()` 允许运行时初始化 - 只初始化一次（线程安全） ### 7.2 互斥锁 ```rust use parking_lot::Mutex; let data = Arc::new(Mutex::new(0)); let data_clone = Arc::clone(&data); thread::spawn(move || { let mut num = data_clone.lock(); // parking_lot 更快 *num += 1; }); ``` **parking_lot vs std::sync::Mutex：** - `parking_lot` 实现更高效 - `std::sync::Mutex` 可能发生系统调用 - 小项目两者性能差异不大 ## 8. 错误处理最佳实践 ### 8.1 ? 运算符链 ```rust fn complex_operation() -> Result<()> { let display = eglGetDisplay(EGL_DEFAULT_DISPLAY)?; eglInitialize(display, ...)?; // ... Ok(()) } ``` ### 8.2 错误转换 ```rust use std::fmt; #[derive(Debug)] enum MyError { IO(std::io::Error), Parse(String), } impl fmt::Display for MyError { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { match self { MyError::IO(e) => write!(f, "IO error: {}", e), MyError::Parse(s) => write!(f, "Parse error: {}", s), } } } impl std::error::Error for MyError {} ``` ## 9. 类型系统技巧 ### 9.1 类型别名 ```rust type EGLDisplay = *mut c_void; type UserId = u64; type TimeStamp = i64; ``` ### 9.2 新类型模式 ```rust struct UserId(u64); impl UserId { fn new(id: u64) -> Self { UserId(id) } } ``` ### 9.3 泛型参数 ```rust struct Container { items: Vec, } impl Container { fn new() -> Self { Container { items: Vec::new() } } } ``` ## 10. 性能优化技巧 ### 10.1 使用 `bytemuck` 零拷贝 ```rust use bytemuck::{Pod, Zeroable}; #[repr(C)] #[derive(Clone, Copy, Pod, Zeroable)] struct Vertex { x: f32, y: f32, } // 直接转换字节（无拷贝） let bytes = bytemuck::cast_slice(&vertices); ``` ### 10.2 预分配容量 ```rust let mut vec = Vec::with_capacity(1000); // 预留空间 ``` ### 10.3 使用 `Cow` 避免克隆 ```rust use std::borrow::Cow; fn process_data(data: Cow) { match data { Cow::Borrowed(s) => println!("借用: {}", s), Cow::Owned(s) => println!("拥有: {}", s), } } ``` ## 11. 测试 ### 11.1 单元测试 ```rust #[cfg(test)] mod tests { use super::*; #[test] fn test_add() { assert_eq!(add(2, 3), 5); } #[test] #[should_panic] fn test_divide_by_zero() { divide(1.0, 0.0).unwrap(); } } ``` ### 11.2 集成测试 ```rust // tests/integration_test.rs use my_crate; #[test] fn test_integration() { let result = my_crate::function(); assert!(result.is_ok()); } ``` ## 项目代码实践建议 ### 1. 改进错误处理 ```rust // 当前代码 if display == EGL_NO_DISPLAY { return Err(napi::Error::from_reason("eglGetDisplay failed")); } // 更好的做法 display.ok_or_else(|| napi::Error::from_reason("eglGetDisplay failed"))?; ``` ### 2. 使用 `Option` 模式 ```rust // 改进前 pub fn start() -> Result<()> { unsafe { if let Some(r) = R.as_mut() { r.start_render_loop(); } } Ok(()) } // 改进后 pub fn start() -> Result<()> { unsafe { R.as_mut() .ok_or_else(|| napi::Error::from_reason("Not initialized"))? .start_render_loop(); } Ok(()) } ``` ### 3. 分离关注点 ```rust // 将初始化逻辑分离 impl GLRenderer { fn create_context(&self) -> napi::Result { // 上下文创建逻辑 } fn create_surface(&self) -> napi::Result { // 表面创建逻辑 } } ``` ## 总结 ### 核心概念回顾 1. **所有权系统** - 自动内存管理 2. **错误处理** - `Result` 和 `Option` 3. **特征** - 多态和代码复用 4. **泛型** - 类型安全的抽象 5. **并发** - `Mutex`、`Arc`、线程 6. **宏** - 元编程能力 7. **FFI** - C 互操作 ### 学习路径 1. 掌握基础语法和所有权 2. 理解错误处理和并发 3. 学习 FFI 和宏编程 4. 阅读优秀开源项目 5. 编写实际项目 ### 推荐资源 - Rust Book: https://doc.rust-lang.org/book/ - Rust by Example: https://doc.rust-lang.org/rust-by-example/ - Rust API Guidelines: https://rust-lang.github.io/api-guidelines/ - 你的项目：继续改进和完善！ --- 上一篇：[Rust 入门进阶教程（二）：模块、特征和并发](./rust-advanced.md) 下一篇：[回到基础教程](./rust-basics.md) ]]> http://herong.info/posts/rust/rust-tutorial-guide http://herong.info/posts/rust/rust-tutorial-guide Mon, 01 Jan 2024 00:00:00 GMT 本文基于实际项目代码，从最基础的语法开始，逐步深入到高级特性。目标读者：有编程基础但从未接触过 Rust 的开发者。 # 第一部分：基础语法篇 ## 1. Hello World 与基本概念 ### 1.1 一个最简单的 Rust 程序 ```rust fn main() { println!("Hello, Rust!"); } ``` **关键点解释：** - `fn` 是 Rust 中定义函数的关键字（function 的缩写） - `main` 是程序的入口点 - `println!` 是个**宏（macro）**，用于输出文本（注意感叹号） - 每行代码以分号 `;` 结尾 ### 1.2 Cargo - Rust 的项目管理工具 Rust 使用 **Cargo** 作为包管理和构建工具，类似于 npm、Maven。 **创建新项目：** ```bash cargo new my_project ``` **项目结构：** ``` my_project/ ├── Cargo.toml # 项目配置和依赖声明 └── src/ └── main.rs # 主程序入口 ``` **在你的代码中的体现：** ```toml [package] name = "focus_gl" version = "0.1.0" edition = "2021" # Rust 版本 [dependencies] # 依赖库 napi = { version = "2", features = ["napi6"] } glow = "0.13" ``` ## 2. 数据类型和变量 ### 2.1 基本数据类型 ```rust // 整数类型 let age: u32 = 30; // 无符号 32 位整数（你的代码第 10 行） let count: i32 = -5; // 有符号 32 位整数 let bytes: u8 = 255; // 8 位（0-255） // 浮点数 let price: f32 = 99.99; // 32 位浮点 let precise: f64 = 3.14159; // 64 位浮点 // 布尔值 let is_active: bool = true; // 字符（4字节，支持 Unicode） let ch: char = '中'; ``` ### 2.2 变量和可变性 **核心概念：默认不可变！** ```rust let x = 5; // 不可变变量 x = 10; // ❌ 编译错误！ let mut y = 5; // 使用 mut 声明可变变量 y = 10; // ✅ 可以改变 ``` **为什么这样设计？** - 防止意外的修改，提高代码安全性 - 编译器可以进行更多优化 ### 2.3 数组和切片 ```rust // 固定大小数组（你的代码第 129 行） let positions: [f32; 24] = [-0.5, -0.5, -0.5, /* ... */]; // 动态数组 Vec（最常用） let mut names: Vec = Vec::new(); names.push("Alice".to_string()); // 或者使用宏 let numbers = vec![1, 2, 3, 4, 5]; ``` **切片（Slice）- 数组的引用：** ```rust let arr = [1, 2, 3, 4, 5]; let slice = &arr[1..3]; // 获取 [2, 3] ``` ## 3. 控制流 ### 3.1 条件语句 ```rust let age = 18; if age >= 18 { println!("成年人"); } else { println!("未成年人"); } // Rust 中 if 是表达式，可以返回值 let status = if age >= 18 { "成年" } else { "未成年" }; ``` ### 3.2 循环 ```rust // loop 无限循环（可 break 退出） loop { println!("无限循环"); break; // 退出 } // while 循环 let mut i = 0; while i < 10 { i += 1; } // for 循环（最常用） for i in 0..10 { println!("{}", i); } for name in names.iter() { println!("{}", name); } ``` ### 3.3 match 表达式（类似 switch，但更强大） ```rust let result = SessionResult::Completed; match result { SessionResult::Ongoing => println!("进行中"), SessionResult::Completed => println!("已完成"), SessionResult::Interrupted => println!("已中断"), } ``` ## 4. 函数 ### 4.1 函数定义 ```rust // 基本函数 fn greet(name: String) { println!("Hello, {}!", name); } // 带返回值的函数 fn add(a: i32, b: i32) -> i32 { a + b // 最后一个表达式作为返回值（无分号） } // 显式 return fn max(a: i32, b: i32) -> i32 { if a > b { return a; } b } ``` ### 4.2 泛型函数（你的代码使用了很多） ```rust // 泛型函数示例 fn get_first(items: &[T]) -> Option<&T> { items.first() } ``` ## 5. 字符串 **Rust 的字符串有两个类型：** ```rust // &str: 字符串切片（不可变） let s1: &str = "Hello"; // String: 可变的字符串（动态分配） let mut s2: String = String::from("Hello"); s2.push_str(" World"); // 相互转换 let s3 = "hello".to_string(); let s4 = s2.as_str(); ``` --- # 第二部分：中级特性篇 ## 6. 所有权系统（Rust 的核心概念） ### 6.1 什么是所有权？ Rust 通过**所有权（Ownership）** 自动管理内存，无需手动 malloc/free，也无需 GC。 **三大规则：** 1. 每个值都有唯一的所有者 2. 同时只能有一个所有者 3. 所有者离开作用域，值被销毁 ```rust let s1 = String::from("hello"); let s2 = s1; // s1 的所有权移给了 s2 // println!("{}", s1); // ❌ 错误！s1 已失效 println!("{}", s2); // ✅ 正确 // 使用借用（引用）来避免移动 let s3 = &s2; // s3 借用了 s2，s2 仍然有效 println!("{}", s2); // ✅ s2 仍然可用 println!("{}", s3); // ✅ s3 也可用 ``` ### 6.2 引用和借用 ```rust // 不可变引用（可以有多个） let s = String::from("hello"); let r1 = &s; let r2 = &s; // ✅ 可以有多个不可变引用 println!("{}", r1); // 可变引用（只能有一个，且不能与其他引用共存） let mut s = String::from("hello"); let r1 = &mut s; // let r2 = &mut s; // ❌ 错误！同一时间只能有一个可变引用 println!("{}", r1); ``` **为什么限制引用？** - 防止数据竞争（Data Race） - 保证线程安全 ### 6.3 生命周期（你的代码第 6 行用到） ```rust // 生命周期注解（通常编译器会自动推断） fn longest<'a>(x: &'a str, y: &'a str) -> &'a str { if x.len() > y.len() { x } else { y } } ``` ## 7. 结构体和枚举 ### 7.1 结构体（Struct） ```rust // 定义结构体 struct Person { name: String, age: u32, } // 创建实例 let person = Person { name: String::from("Alice"), age: 30, }; // 访问字段 println!("{}", person.name); ``` **在你的代码中的应用（第 2-5 行）：** ```rust #[derive(Clone, Copy)] // 自动生成 Clone 和 Copy 特征 pub struct Instance { pub pos: [f32; 3], pub color: [f32; 4], } ``` ### 7.2 枚举（Enum） ```rust // 定义枚举 enum Color { Red, Green, Blue, } // 带数据的枚举（你的代码第 2-6 行） enum SessionResult { Ongoing, Completed, Interrupted, } // 使用 match 处理 match result { SessionResult::Ongoing => println!("进行中"), _ => println!("其他状态"), } ``` ### 7.3 方法和关联函数 ```rust impl Person { // 关联函数（类似静态方法） fn new(name: String, age: u32) -> Self { Self { name, age } } // 方法（第一个参数是 &self） fn greet(&self) { println!("Hello, I'm {}", self.name); } // 可变方法 fn have_birthday(&mut self) { self.age += 1; } } // 使用 let mut alice = Person::new("Alice".to_string(), 30); alice.greet(); alice.have_birthday(); ``` **在你的代码中的应用（整个 GLRenderer impl）：** ```rust impl GLRenderer { pub fn new(surface_id: String, width: u32, height: u32) -> napi::Result { // ... 构造逻辑 Ok(Self { /* ... */ }) } pub fn init_gl_pipeline(&mut self) -> napi::Result<()> { // ... 初始化逻辑 Ok(()) } } ``` ## 8. 特征（Trait）- 类似接口 ```rust // 定义特征 trait Drawable { fn draw(&self); } // 为类型实现特征 struct Circle { radius: f64, } impl Drawable for Circle { fn draw(&self) { println!("Drawing circle with radius {}", self.radius); } } // 使用特征作为参数 fn render(item: impl Drawable) { item.draw(); } ``` **你的代码中使用的特征：** - `HasContext` from `glow` crate - `Drop` trait（第 380 行） ## 9. 错误处理 ### 9.1 Result 类型 ```rust // Result 表示可能成功(T) 或失败(E) enum Result { Ok(T), // 成功 Err(E), // 错误 } // 示例 fn divide(a: f64, b: f64) -> Result { if b == 0.0 { Err("Cannot divide by zero".to_string()) } else { Ok(a / b) } } // 处理 Result match divide(10.0, 2.0) { Ok(result) => println!("Result: {}", result), Err(e) => println!("Error: {}", e), } ``` ### 9.2 使用 ? 运算符（你的代码大量使用） ```rust fn read_file() -> Result { let contents = std::fs::read_to_string("file.txt")?; // 遇到错误自动返回 Ok(contents) } // 等价于 fn read_file() -> Result { let contents = match std::fs::read_to_string("file.txt") { Ok(c) => c, Err(e) => return Err(e), }; Ok(contents) } ``` **在你的代码中：** ```rust pub fn new(surface_id: String, width: u32, height: u32) -> napi::Result { unsafe { let display = eglGetDisplay(EGL_DEFAULT_DISPLAY); if display == EGL_NO_DISPLAY { return Err(napi::Error::from_reason("eglGetDisplay failed")); // 返回错误 } // ... Ok(Self { /* ... */ }) // 返回成功 } } ``` ## 10. Option 类型 ```rust // Option 表示可能有值(Some)或没有值(None) enum Option { Some(T), None, } // 示例 let numbers = vec![1, 2, 3]; let first = numbers.first(); // 返回 Option<&i32> match first { Some(value) => println!("First: {}", value), None => println!("No elements"), } // 使用 unwrap（危险：None 会 panic） let value = first.unwrap(); // 安全的 unwrap let value = first.unwrap_or(&0); // 如果是 None 返回默认值 ``` **在你的代码中的使用（第 7 行）：** ```rust static mut R: Option = None; // 可能没有渲染器 // 使用时检查 if let Some(r) = R.as_mut() { // 安全访问 r.start_render_loop(); } ``` --- # 第三部分：高级特性篇 ## 11. 模块系统 ### 11.1 模块定义 ```rust // src/lib.rs 或 main.rs mod renderer; // 声明 renderer 模块 // src/renderer/mod.rs 或 src/renderer.rs pub mod shaders; // 公开子模块 mod cubes; // 私有子模块 ``` ### 11.2 使用模块 ```rust // 使用绝对路径 use crate::renderer::GLRenderer; // 使用相对路径 use renderer::cubes::Instance; // 重命名 use std::collections::HashMap as Map; ``` ## 12. 宏（Macro） ### 12.1 常见的宏 ```rust println!("Hello, {}!", name); // 格式化输出 vec![1, 2, 3]; // 创建向量 format!("Hello, {}!", name); // 格式化字符串 panic!("Something went wrong!"); // 程序终止 ``` ### 12.2 属性宏（你的代码使用） ```rust // derive 宏 - 自动生成代码 #[derive(Clone, Copy, Debug, Serialize, Deserialize)] pub struct Instance { // ... } // 函数属性 #[napi] pub fn init(surface_id: String, width: u32, height: u32) -> Result<()> { // ... } ``` ## 13. 并发和并行 ### 13.1 线程 ```rust use std::thread; let handle = thread::spawn(|| { // 新线程执行的代码 println!("Hello from thread!"); }); handle.join().unwrap(); // 等待线程完成 ``` ### 13.2 互斥锁（你的代码第 55 行使用） ```rust use std::sync::{Arc, Mutex}; let data = Arc::new(Mutex::new(0)); let data_clone = Arc::clone(&data); thread::spawn(move || { let mut num = data_clone.lock().unwrap(); *num += 1; }); ``` **你的代码中使用的 parking_lot：** ```rust use parking_lot::Mutex; static RUNNING: Lazy> = Lazy::new(|| Mutex::new(false)); // 使用 *RUNNING.lock() = true; // parking_lot 更高效 ``` ## 14. 智能指针 ### 14.1 Box - 堆分配 ```rust let b = Box::new(5); // 将值分配到堆上 ``` ### 14.2 Rc - 引用计数（单线程） ```rust use std::rc::Rc; let data = Rc::new(5); let data2 = Rc::clone(&data); // 引用计数增加 ``` ### 14.3 Arc - 原子引用计数（多线程） ```rust use std::sync::Arc; let data = Arc::new(5); let data2 = Arc::clone(&data); // 可以在线程间共享 ``` ## 15. 特征对象（Trait Objects） ```rust trait Animal { fn speak(&self); } struct Dog; impl Animal for Dog { fn speak(&self) { println!("Woof!"); } } let animals: Vec> = vec![ Box::new(Dog), ]; for animal in animals { animal.speak(); } ``` --- # 第四部分：实战应用篇 ## 16. 你的代码中用到的关键概念解析 ### 16.1 安全和不安全代码 ```rust unsafe { // 需要 unsafe 的操作： // 1. 解引用裸指针 // 2. 调用 unsafe 函数 // 3. 访问可变静态变量 // 4. 实现 unsafe trait } // 你的代码第 89 行 static mut R: Option = None; // 可变静态变量必须用 unsafe ``` ### 16.2 外部函数接口（FFI） ```rust // 你的代码第 48-58 行 extern "C" { fn eglGetDisplay(native_display: *mut c_void) -> EGLDisplay; fn eglInitialize(dpy: EGLDisplay, major: *mut i32, minor: *mut i32) -> i32; // ... } // 调用 C 函数 unsafe { let display = eglGetDisplay(EGL_DEFAULT_DISPLAY); } ``` ### 16.3 泛型和特征约束 ```rust // 泛型函数 fn find_first(items: &[T], predicate: P) -> Option<&T> where P: Fn(&T) -> bool, // P 必须是可以调用的函数 { items.iter().find(|item| predicate(item)) } ``` ### 16.4 迭代器 ```rust // 你的代码第 270 行 let raw: Vec = instances.iter().map(|it| RawInst { pos: it.pos, color: it.color }).collect(); // 分解说明： instances.iter() // 创建迭代器 .map(|it| RawInst { /* ... */ }) // 转换每个元素 .collect(); // 收集结果 // 更多迭代器方法 numbers.iter() .filter(|&x| x > 5) // 过滤 .map(|x| x * 2) // 转换 .collect(); ``` ## 17. 模式匹配进阶 ### 17.1 解构 ```rust // 解构结构体 let person = Person { name: "Alice".to_string(), age: 30 }; let Person { name, age } = person; // 解构元组 let (x, y) = (3, 4); // if let 语法糖 if let Some(value) = option { println!("Found: {}", value); } // 你的代码第 31 行 if let Some(r) = R.as_mut() { r.start_render_loop(); } ``` ### 17.2 守卫（Guard） ```rust match value { Some(x) if x > 10 => println!("Large number"), Some(x) => println!("Small number"), None => println!("No value"), } ``` ## 18. 生命周期实战 ```rust // 结构体持有引用需要生命周期注解 struct GLRenderer<'a> { gl: &'a glow::Context, } impl<'a> GLRenderer<'a> { fn new(gl: &'a glow::Context) -> Self { Self { gl } } } // 高级生命周期 fn longest<'a, 'b>(x: &'a str, y: &'b str) -> &'a str where 'a: 'b, // a 的生命周期至少和 b 一样长 { if x.len() > y.len() { x } else { y } } ``` ## 19. 异步编程（Future 和 async/await） ```rust use tokio; // 异步运行时 async fn fetch_data() -> Result { // 异步操作 let response = reqwest::get("https://example.com").await?; let text = response.text().await?; Ok(text) } #[tokio::main] async fn main() { let result = fetch_data().await; } ``` --- # 第五部分：专家级话题 ## 20. 高级类型系统 ### 20.1 关联类型 ```rust trait Iterator { type Item; // 关联类型 fn next(&mut self) -> Option; } impl Iterator for Counter { type Item = i32; fn next(&mut self) -> Option { Some(1) } } ``` ### 20.2 高级特征绑定 ```rust // 多个特征约束 fn process(item: T) where T: Clone + Debug + Display, { // ... } // 特征继承 trait Read: BufRead { // Read 的所有方法 } // 默认方法实现 trait Default { fn default() -> Self; } // 特征对象 fn process(items: Vec>) { // ... } ``` ## 21. 宏编程 ### 21.1 声明宏（macro_rules!） ```rust macro_rules! vec { ( $( $x:expr ),* ) => { { let mut temp_vec = Vec::new(); $( temp_vec.push($x); )* temp_vec } }; } ``` ### 21.2 过程宏 ```rust // derive 宏示例 #[derive(Clone)] struct MyStruct { // ... } // 属性宏 #[route(GET, "/")] fn index() { } // 函数宏 println!("Hello"); ``` ## 22. 内存布局和优化 ### 22.1 零成本抽象 ```rust // Rust 的迭代器是零成本的 let sum: i32 = numbers.iter().map(|x| x * 2).sum(); // 编译后和手写循环一样高效 ``` ### 22.2 内存布局 ```rust // #[repr(C)] 指定 C 兼容的内存布局 #[repr(C)] struct Point { x: f32, y: f32, } // #[repr(packed)] 紧密打包 #[repr(packed)] struct Compact { x: u8, y: u16, } ``` ### 22.3 未定义行为（UB） ```rust unsafe { // 错误的操作会导致未定义行为 let mut x = 1; let y = &mut x; let z = &x; // 错误：同时有可变和不可变引用 } ``` ## 23. 高级并发模式 ### 23.1 通道（Channel） ```rust use std::sync::mpsc; let (sender, receiver) = mpsc::channel(); thread::spawn(move || { sender.send("Hello").unwrap(); }); let message = receiver.recv().unwrap(); ``` ### 23.2 无锁数据结构 ```rust use std::sync::atomic::{AtomicUsize, Ordering}; let counter = AtomicUsize::new(0); counter.fetch_add(1, Ordering::SeqCst); ``` ### 23.3 条件变量 ```rust use std::sync::{Arc, Mutex, Condvar}; let pair = Arc::new((Mutex::new(false), Condvar::new())); let (lock, cvar) = &*pair; // 等待条件满足 let mut started = lock.lock().unwrap(); while !*started { started = cvar.wait(started).unwrap(); } ``` ## 24. 内联汇编 ```rust use std::arch::asm; unsafe { asm!("nop"); } ``` ## 25. 自定义堆分配器 ```rust use std::alloc::{GlobalAlloc, Layout}; struct MyAllocator; unsafe impl GlobalAlloc for MyAllocator { unsafe fn alloc(&self, layout: Layout) -> *mut u8 { std::alloc::alloc(layout) } unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) { std::alloc::dealloc(ptr, layout) } } ``` --- # 总结：实践建议 ## 学习路径 1. **第 1-2 周：基础语法** - 变量、数据类型、控制流 - 函数、结构体、枚举 - 所有权和借用 2. **第 3-4 周：中级特性** - 模块系统 - 错误处理（Result, Option） - 特征（Trait） 3. **第 5-6 周：实战项目** - 使用 Cargo 创建项目 - 熟悉常用 crate - 调试和测试 4. **持续学习：高级特性** - 并发编程 - 宏编程 - 性能优化 ## 常见陷阱 1. **所有权混淆** - 忘记使用 `mut` 声明可变变量 - 试图使用已移动的值 2. **生命周期错误** - 返回对临时值的引用 - 生命周期参数使用不当 3. **借用检查** - 同时持有可变和不可变引用 - 闭包捕获导致借用问题 ## 推荐资源 - **官方文档**：https://doc.rust-lang.org/ - **Rust By Example**：https://doc.rust-lang.org/rust-by-example/ - **Rust Book 中文版**：https://kaisery.github.io/trpl-zh-cn/ - **Crates.io**：Rust 的包仓库 ## 你的项目中的关键概念总结 1. **N-API 集成**：使用 `#[napi]` 宏导出函数供 Node.js 调用 2. **OpenGL 渲染**：通过 FFI 调用 OpenGL ES 函数 3. **内存安全**：使用 `unsafe` 块调用 C API，但管理安全的 Rust 抽象 4. **错误处理**：大量使用 `Result` 类型和 `?` 运算符 5. **模块组织**：清晰的模块结构（renderer, shaders, cubes） 6. **RAII**：自动资源管理（Drop trait） --- _祝你学习 Rust 愉快！🎉_ ]]> http://herong.info/posts/rust/rust-tutorial- http://herong.info/posts/rust/rust-tutorial- Mon, 01 Jan 2024 00:00:00 GMT 一套完整的 Rust 学习路径，从零基础到项目实战，基于实际项目代码编写。 ## 📚 教程导航 ### 第一篇：基础语法篇 **[Rust 入门基础教程（一）：语法基础](./rust-basics.md)** **适合人群：** 从未接触过 Rust 的开发者 **主要内容：** - ✅ Hello World 与 Cargo - ✅ 变量和数据类型 - ✅ 控制流（if/else, loop, match） - ✅ 函数定义 - ✅ 所有权系统（Rust 核心） - ✅ 结构体和枚举 - ✅ 错误处理（Result, Option） **学习时间：** 1-2 周 --- ### 第二篇：进阶特性篇 **[Rust 入门进阶教程（二）：模块、特征和并发](./rust-advanced.md)** **适合人群：** 已经掌握基础语法的开发者 **主要内容：** - 📦 模块系统和可见性 - 🎯 特征（Trait）和多态 - ⏱️ 生命周期详解 - 🔀 泛型编程 - 🎪 智能指针（Box, Rc, Arc） - 🔄 并发编程（线程、通道） - ⚡ 异步编程（async/await） **学习时间：** 2-3 周 --- ### 第三篇：实战应用篇 **[Rust 实战教程（三）：项目代码详解](./rust-practical.md)** **适合人群：** 已掌握进阶特性的开发者 **主要内容：** - 🔌 N-API 集成 - 🔗 外部函数接口（FFI） - 💾 内存管理和 RAII - 🔄 迭代器和函数式编程 - 🎭 闭包详解 - ⚙️ 宏编程 - 🚀 性能优化技巧 - 🧪 测试实践 **学习时间：** 2-3 周 --- ## 🎯 学习路径推荐 ### 新手路径（1-2 个月） 1. **第 1-2 周** - 阅读第一篇：基础语法 - 完成所有练习 - 熟悉 Rust Playground 2. **第 3-4 周** - 阅读第二篇：进阶特性 - 练习并发编程 - 编写简单项目 3. **第 5-6 周** - 阅读第三篇：实战应用 - 分析实际项目代码 - 尝试改进项目 4. **第 7-8 周** - 独立完成一个小项目 - 阅读开源 Rust 项目 - 参与 Rust 社区 ### 有经验开发者路径（2-4 周） 1. **第 1 周** - 快速阅读第一篇（重点关注所有权） - 直接学习第二篇核心概念 - 练习高级特性 2. **第 2 周** - 深入学习 FFI 和宏编程 - 分析项目代码实现 - 研究性能优化 3. **第 3-4 周** - 重构和改进代码 - 贡献到开源项目 - 成为 Rust 专家！ --- ## 🛠️ 必备工具 ### 1. 开发环境 ```bash # 安装 Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # 安装工具链 rustup install stable rustup default stable ``` ### 2. 推荐编辑器插件 - **VS Code**: rust-analyzer 插件 - **JetBrains**: Rust Plugin - **Vim/Neovim**: coc-rust-analyzer ### 3. 实用工具 ```bash # 格式化代码 cargo fmt # 检查代码 cargo clippy # 查看文档 cargo doc --open ``` --- ## 📖 学习资源 ### 官方资源 - [The Rust Book](https://doc.rust-lang.org/book/) - 官方权威教程 - [Rust by Example](https://doc.rust-lang.org/rust-by-example/) - 通过例子学习 - [The Rust Reference](https://doc.rust-lang.org/reference/) - 语言参考 ### 推荐书籍 1. **《Rust 程序设计语言》** - 官方书籍中文版 2. **《Rust in Action》** - 实战导向 3. **《Programming Rust》** - 深入理解 ### 在线课程 - [Rustlings](https://github.com/rust-lang/rustlings) - 小练习 - [Exercism](https://exercism.org/tracks/rust) - 编程练习平台 - [Advent of Code](https://adventofcode.com/) - 年度编程挑战 --- ## 🎓 项目代码中的核心概念 ### 你项目中用到的关键特性 1. **N-API 宏** - `#[napi]` 导出到 JavaScript 2. **FFI** - `extern "C"` 调用 C 函数 3. **RAII** - `Drop` trait 自动资源管理 4. **Option/Result** - 错误处理模式 5. **泛型** - 类型安全的抽象 6. **智能指针** - `Arc`, `Mutex` 并发安全 7. **迭代器** - 函数式编程风格 8. **宏编程** - `derive` 自动生成代码 --- ## ⚡ 快速开始 ### 第一个 Rust 程序 ```rust fn main() { println!("Hello, Rust!"); } ``` ### 运行命令 ```bash rustc main.rs # 编译 ./main # 运行（Linux/Mac） main.exe # 运行（Windows） ``` ### 使用 Cargo ```bash cargo new hello_world cd hello_world cargo run ``` --- ## 🤝 社区支持 ### 获取帮助 - [用户论坛](https://users.rust-lang.org/) - [Stack Overflow](https://stackoverflow.com/questions/tagged/rust) - [Reddit - r/rust](https://www.reddit.com/r/rust/) - [Discord](https://discord.gg/rust-lang) ### 中文社区 - [Rust 中文社区](https://rust.cc/) - [Rust 中文论坛](https://rust-lang-cn.org/) - [Rust 中文文档](https://rustcc.cn/) --- ## 🎯 学习目标 ### 初级（1-3 个月） - ✅ 掌握基础语法 - ✅ 理解所有权系统 - ✅ 能编写简单程序 - ✅ 熟悉错误处理 ### 中级（3-6 个月） - ✅ 熟练使用标准库 - ✅ 理解并发编程 - ✅ 能写测试代码 - ✅ 了解 Rust 生态系统 ### 高级（6 个月以上） - ✅ 深入理解类型系统 - ✅ 掌握高级生命周期 - ✅ 熟练使用宏编程 - ✅ 能进行性能优化 - ✅ 可以贡献开源项目 --- ## 💡 学习建议 ### Do ✅ - 多写代码，多做练习 - 阅读官方文档 - 参与开源项目 - 加入社区讨论 - 写学习笔记 ### Don't ❌ - 不要过度依赖 AI 补全 - 不要跳过基础概念 - 不要害怕编译器错误 - 不要忽视所有权规则 - 不要孤立学习，要结合实际项目 --- ## 🚀 进阶方向 ### 系统编程 - 操作系统开发 - 嵌入式编程 - 网络编程 ### Web 开发 - [Axum](https://github.com/tokio-rs/axum) - Web 框架 - [Rocket](https://rocket.rs/) - Web 框架 - [Actix](https://actix.rs/) - Web 框架 ### 游戏开发 - [Bevy](https://bevyengine.org/) - 游戏引擎 - [Amethyst](https://amethyst.rs/) - 游戏引擎 ### 机器学习 - [Candle](https://github.com/huggingface/candle) - ML 框架 - [burn](https://burn.dev/) - Deep Learning 框架 --- ## 📊 学习进度追踪 使用以下清单追踪你的学习进度： ### 基础篇 - [ ] 理解变量和类型 - [ ] 掌握所有权概念 - [ ] 能写基本控制流 - [ ] 理解函数和结构体 - [ ] 熟悉错误处理 ### 进阶篇 - [ ] 理解特征和实现 - [ ] 掌握生命周期 - [ ] 熟悉泛型编程 - [ ] 理解并发编程 - [ ] 能使用异步编程 ### 实战篇 - [ ] 能调用 C 函数 - [ ] 理解宏编程 - [ ] 掌握性能优化 - [ ] 能写测试代码 - [ ] 完成项目实战 --- ## 🎉 开始你的 Rust 之旅 选择适合你的学习路径，开始学习吧！ - **完全新手？** → 从 [第一篇：基础语法](./rust-basics.md) 开始 - **有其他语言经验？** → 快速浏览第一篇，重点看第二篇 - **想快速上手项目？** → 直接看第三篇，遇到问题回头查 祝学习愉快！🚀 --- **更新时间：** 2024 年 1 月 **作者：** Rust 学习社区 **反馈：** 如果你有任何问题或建议，欢迎提 Issue 或 Pull Request ]]> http://herong.info/posts/swift-quickstart/0-提示词 http://herong.info/posts/swift-quickstart/0-提示词 Wed, 23 Sep 2026 11:45:26 GMT http://herong.info/posts/swift-quickstart/01-语法速览 http://herong.info/posts/swift-quickstart/01-语法速览 Sun, 14 Sep 2025 00:00:00 GMT 本文属于 Swift 入门速成系列，帮助你在 **8 小时内掌握最常用的语法与特性**，快速读懂代码。 > 本篇作为第一篇，带你 **一眼看懂 Swift 的常见语法**，相当于一个“速查表”。 ## 基本语法特点 - **强类型语言**：所有变量、常量都有确定类型。 - **类型推断**：大多数时候不用显式写类型，编译器能自动推断。 - **安全性强**：默认变量必须初始化，避免空指针。 - **现代简洁**：省去了大量冗余符号，代码更接近自然语言。 ## 变量与常量 ```swift let pi = 3.14159 // 常量，不能修改 var age = 18 // 变量，可以修改 age = 20 // ✅ 可以修改 // pi = 3.14 // ❌ 报错：常量不可修改 ``` ## 常见数据类型 ```swift let name: String = "Swift" let score: Int = 95 let price: Double = 19.99 let passed: Bool = true ``` ## 字符串插值 ```swift let name = "Alice" let age = 20 print("Hello, my name is \(name), I am \(age) years old.") ``` ## 数组与字典 ```swift // 数组 var numbers = [1, 2, 3, 4] numbers.append(5) print(numbers[0]) // 输出 1 // 字典 var user = ["name": "Bob", "age": "22"] print(user["name"] ?? "Unknown") // Bob ``` ## 条件语句 ```swift let score = 85 if score >= 90 { print("优秀") } else if score >= 60 { print("及格") } else { print("不及格") } ``` ## 循环 ```swift for i in 1...5 { print("第 \(i) 次") } var n = 3 while n > 0 { print(n) n -= 1 } ``` ## 函数 ```swift func greet(name: String) -> String { return "Hello, \(name)" } print(greet(name: "Swift")) // Hello, Swift ``` ## 可选类型（Optionals） ```swift var nickname: String? = nil nickname = "小明" // 安全解包 if let nick = nickname { print("昵称：\(nick)") } ``` ## 小结 这一篇带你快速扫了一遍 **Swift 最常见的语法**： - 变量与常量（`var` / `let`） - 常见数据类型（`String`、`Int`、`Double`、`Bool`） - 数组与字典 - 条件与循环 - 函数 - 可选类型（`?` 和 `if let`） ]]> http://herong.info/posts/swift-quickstart/02-变量与常量 http://herong.info/posts/swift-quickstart/02-变量与常量 Sun, 14 Sep 2025 00:00:00 GMT 注意：`lazy` 只能修饰 **var**，不能修饰 **let**。 ## 可变性原则 Swift 推荐： - **默认用 `let`**，只有需要修改时才用 `var`。 - 这样可以避免无意的修改，提高代码安全性。 ## 小结 - `var` 定义变量，可变。 - `let` 定义常量，不可变。 - 默认用 `let`，这是 Swift 的最佳实践。 - 类型推断让代码更简洁，但在需要时可显式声明。 ]]> http://herong.info/posts/swift-quickstart/03-流程控制 http://herong.info/posts/swift-quickstart/03-流程控制 Sun, 14 Sep 2025 00:00:00 GMT 程序的核心就是控制执行流程。Swift 提供了清晰的条件判断和循环语法，语义直观，易读易写。 ## if 条件语句 ```swift let score = 85 if score >= 90 { print("优秀") } else if score >= 60 { print("及格") } else { print("不及格") } ``` > **注意**：条件表达式必须是布尔值，不能像 C 那样用 `1` 或 `0`。 ### 版本兼容性检查：#available ```swift // iOS 版本兼容性检查 if #available(iOS 16.0, *) { // iOS 16+ 可用的代码 let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: "example.com") // 使用 Passkeys 功能 } else { // iOS 16 以下的降级处理 print("需要 iOS 16 或更高版本") } ``` #### #available 语法详解 ```swift if #available(平台 版本号, *) { // 新版本可用的代码 } else { // 旧版本的兜底处理 } ``` **参数说明**： - `iOS 16.0`：指定最低支持的 iOS 版本 - `*`：表示其他平台使用当前部署目标版本 #### 实际应用场景 ```swift // 1. 新 API 的兼容性处理 func setupPasskeys() { if #available(iOS 16.0, *) { // 使用 iOS 16+ 的 Passkeys API let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: rpId) let request = provider.createCredentialRegistrationRequest( challenge: challengeData, name: userName, userID: userIdData ) performPasskeyAuthentication(request) } else { // 降级到传统密码登录 showPasswordLogin() } } // 2. UI 组件的版本适配 func setupUI() { if #available(iOS 15.0, *) { // 使用 iOS 15+ 的新 UI 组件 let button = UIButton(configuration: .filled()) button.configuration?.title = "登录" } else { // 使用传统的 UIButton 设置 let button = UIButton(type: .system) button.setTitle("登录", for: .normal) button.backgroundColor = .systemBlue } } // 3. 多平台版本检查 func setupCrossplatform() { if #available(iOS 14.0, macOS 11.0, watchOS 7.0, tvOS 14.0, *) { // 所有平台都支持的新功能 useNewFeature() } else { // 兜底方案 useOldFeature() } } ``` #### 与 @available 的区别 ```swift // @available - 标记函数/类的可用性 @available(iOS 16.0, *) func createPasskey() { // 这个函数只在 iOS 16+ 可用 } // #available - 运行时检查版本 func someFunction() { if #available(iOS 16.0, *) { createPasskey() // 只有在 iOS 16+ 才调用 } } ``` #### 常见的版本检查模式 ```swift // 模式1：功能降级 func authenticateUser() { if #available(iOS 16.0, *) { // 优先使用 Passkeys setupPasskeys() } else if #available(iOS 13.0, *) { // 次选使用 Face ID/Touch ID setupBiometrics() } else { // 最后使用密码 setupPasswordAuth() } } // 模式2：错误提示 func checkCompatibility() { guard #available(iOS 16.0, *) else { showAlert(message: "此功能需要 iOS 16 或更高版本") return } // 继续执行 iOS 16+ 的代码 enableAdvancedFeatures() } // 模式3：条件编译结合 #if swift(>=5.7) if #available(iOS 16.0, *) { // Swift 5.7 + iOS 16 的最新功能 } #endif ``` #### 实际项目中的最佳实践 ```swift class AuthenticationManager { func register(_ options: String, callback: @escaping (String) -> Void) { // 版本检查应该在功能入口处进行 guard #available(iOS 16.0, *) else { callback(errorJSON("iOS 16+ required for Passkeys")) return } // 继续执行 Passkeys 注册逻辑 performPasskeyRegistration(options, callback) } private func performPasskeyRegistration(_ options: String, _ callback: @escaping (String) -> Void) { // 这里可以安全使用 iOS 16+ API，因为已经检查过版本 let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: rpId) // ... } private func errorJSON(_ message: String) -> String { return """ { "ok": false, "errMsg": "\(message)" } """ } } ``` ## switch 语句 ```swift let grade = "B" switch grade { case "A": print("非常好") case "B": print("良好") case "C": print("及格") default: print("不及格") } ``` 特点： - **必须覆盖所有情况**，否则要写 `default`。 - **无需写 `break`**，匹配后自动退出。 ### switch 的进阶用法 ```swift let point = (1, 1) switch point { case (0, 0): print("原点") case (let x, 0): print("在 X 轴上，x=\(x)") case (0, let y): print("在 Y 轴上，y=\(y)") case (-2...2, -2...2): print("在 (-2,2) 范围内") default: print("其他位置") } ``` > Swift 的 `switch` 很强大，支持区间、元组、条件匹配。 ## while 循环 ```swift var n = 3 while n > 0 { print(n) n -= 1 } ``` ## repeat-while 循环（至少执行一次） ```swift var m = 0 repeat { print("执行一次：m=\(m)") m += 1 } while m < 3 ``` ## for-in 循环 ```swift for i in 1...5 { // 闭区间，包含 5 print(i) } for i in 1..<5 { // 半开区间，不包含 5 print(i) } let names = ["Alice", "Bob", "Charlie"] for name in names { print("Hello, \(name)") } ``` ## 控制跳转 ```swift for i in 1...5 { if i == 3 { continue // 跳过当前循环 } if i == 4 { break // 提前结束循环 } print(i) } ``` ## 小结 - `if-else`：最常见的条件判断。 - `switch`：比很多语言更强大，支持模式匹配。 - 循环包括 `while`、`repeat-while`、`for-in`，最后一个最常用。 - `continue` 和 `break` 用于跳转控制。 ]]> http://herong.info/posts/swift-quickstart/04-函数 http://herong.info/posts/swift-quickstart/04-函数 Sun, 14 Sep 2025 00:00:00 GMT 函数是 Swift 程序的基本组成单位，既能封装逻辑，也能复用代码。 ## 基本函数 ```swift func sayHello() { print("Hello, Swift!") } sayHello() // 调用 ``` ## 带参数的函数 ```swift func greet(name: String) { print("Hello, \(name)!") } greet(name: "Alice") ``` ## 多个参数 ```swift func add(a: Int, b: Int) -> Int { return a + b } let result = add(a: 3, b: 5) print(result) // 8 ``` > 使用 `->` 指定返回值类型。 ## 外部参数名 Swift 默认函数参数既有 **外部名**（调用时用的）也有 **内部名**（函数体内用的）。 ```swift func multiply(x a: Int, y b: Int) -> Int { return a * b } let r = multiply(x: 2, y: 3) print(r) // 6 ``` ## 省略外部参数名 用 `_` 可以省略外部参数名，让调用更简洁： ```swift func divide(_ a: Double, _ b: Double) -> Double { return a / b } print(divide(10, 2)) // 5.0 ``` ## 默认参数 ```swift func greet(name: String = "游客") { print("你好，\(name)！") } greet() // 你好，游客！ greet(name: "小明") // 你好，小明！ ``` ## 可变参数 一个参数可以接收多个值： ```swift func sum(_ numbers: Int...) -> Int { var total = 0 for n in numbers { total += n } return total } print(sum(1, 2, 3, 4)) // 10 ``` ## 返回多个值（元组） ```swift func minMax(_ numbers: [Int]) -> (min: Int, max: Int)? { if numbers.isEmpty { return nil } var minVal = numbers[0] var maxVal = numbers[0] for n in numbers { if n < minVal { minVal = n } if n > maxVal { maxVal = n } } return (minVal, maxVal) } if let result = minMax([3, 7, 2, 9]) { print("最小值: \(result.min), 最大值: \(result.max)") } ``` ## 小结 - `func` 定义函数。 - 参数可以有外部名，也可以用 `_` 省略。 - 支持默认参数和可变参数。 - 函数可以返回单个值，也可以返回元组。 ]]> http://herong.info/posts/swift-quickstart/05-集合 http://herong.info/posts/swift-quickstart/05-集合 Sun, 14 Sep 2025 00:00:00 GMT Swift 提供了三种常用集合类型：**数组（Array）**、**集合（Set）** 和 **字典（Dictionary）**。掌握它们就能处理大部分数据存储与操作。 ## 数组（Array） 数组是有序的元素集合，可以包含重复值。 ```swift var numbers: [Int] = [1, 2, 3, 4] // 添加元素 numbers.append(5) // 访问元素 print(numbers[0]) // 1 // 遍历 for num in numbers { print(num) } ``` 简写： ```swift let fruits = ["Apple", "Banana", "Cherry"] print(fruits.count) // 3 print(fruits.contains("Banana")) // true ``` ## 集合（Set） 集合是 **无序且唯一** 的元素集合。 ```swift var set: Set = ["A", "B", "C"] set.insert("D") set.insert("A") // 已存在，不会重复 print(set.contains("C")) // true // 遍历（顺序不保证） for item in set { print(item) } ``` 集合常用于 **去重**： ```swift let nums = [1, 2, 2, 3, 3, 4] let uniqueNums = Set(nums) print(uniqueNums) // {2, 3, 1, 4} ``` ## 字典（Dictionary） 字典是 **键值对** 的集合。 ```swift var dict: [String: Int] = [ "Alice": 25, "Bob": 30 ] // 访问 print(dict["Alice"]) // Optional(25) // 修改 dict["Alice"] = 26 // 新增 dict["Charlie"] = 22 // 遍历 for (name, age) in dict { print("\(name): \(age)") } ``` ## 集合运算（Set 特有） ```swift let set1: Set = [1, 2, 3] let set2: Set = [3, 4, 5] // 交集 print(set1.intersection(set2)) // [3] // 并集 print(set1.union(set2)) // [1, 2, 3, 4, 5] // 差集 print(set1.subtracting(set2)) // [1, 2] ``` ## 小结 - **Array**：有序，可重复 → 适合顺序存储。 - **Set**：无序，唯一 → 适合去重、集合运算。 - **Dictionary**：键值对 → 适合映射关系。 ]]> http://herong.info/posts/swift-quickstart/06-可选类型与空安全 http://herong.info/posts/swift-quickstart/06-可选类型与空安全 Sun, 14 Sep 2025 00:00:00 GMT Swift 语言最突出的特性之一就是 **空安全（null safety）**，它通过 **可选类型（Optional）** 来避免常见的空指针错误。 ## 什么是可选类型？ 在 Swift 中，变量默认必须有值。如果可能为空，就要用 `?` 声明为 **可选类型**： ```swift var name: String? = "Alice" name = nil // 合法，因为是可选类型 ``` 普通变量不能为 `nil`： ```swift var age: Int = 18 // age = nil ❌ 错误 ``` ## 解包（Unwrapping） ### 1. 强制解包（!） 如果确定有值，可以用 `!` 取出： ```swift let name: String? = "Bob" print(name!) // Bob ``` ⚠️ 如果为 `nil` 会崩溃： ```swift let n: String? = nil print(n!) // ❌ 崩溃 ``` ### 2. 可选绑定（if let） 更安全的写法： ```swift var name: String? = "Charlie" if let n = name { print("Hello, \(n)") // Hello, Charlie } else { print("No name") } ``` ### 3. 可选绑定（guard let） 常用于函数中提前退出： ```swift func greet(_ name: String?) { guard let n = name else { print("No name") return } print("Hello, \(n)") } greet("David") // Hello, David greet(nil) // No name ``` #### guard let 的实战应用：Base64URL 编码 ```swift // 实际项目中的 guard let 使用模式 private func b64url(_ data: Data?) -> String { guard let d = data else { return "" } // 继续处理 d（已确保不为 nil） return d.base64EncodedString() .replacingOccurrences(of: "+", with: "-") .replacingOccurrences(of: "/", with: "_") .replacingOccurrences(of: "=", with: "") } // 使用示例 let someData: Data? = "Hello".data(using: .utf8) let result = b64url(someData) // 返回 Base64URL 编码字符串 let nilResult = b64url(nil) // 返回空字符串 "" ``` #### 多重 guard let 与 as? 组合 ```swift // 复杂的 JSON 数据解析与类型转换 func parsePasskeyOptions(_ data: Data, _ cb: @escaping (String) -> Void) { guard let pub = try? JSONSerialization.jsonObject(with: data) as? [String: Any], let rp = pub["rp"] as? [String: Any], let rpId = rp["id"] as? String, let challengeB64 = pub["challenge"] as? String, let user = pub["user"] as? [String: Any], let userIdB64 = user["id"] as? String, let userName = user["name"] as? String else { cb(toJSON(["ok": false, "errMsg": "bad options"])) return } // 所有解析都成功，继续处理 processPasskeyRegistration(rpId: rpId, challenge: challengeB64, userId: userIdB64, userName: userName) } ``` #### as? String else 详解 **语法结构**： ```swift let userName = user["name"] as? String // ↑ ↑ ↑ // 字典取值 安全转换 目标类型 ``` **执行流程**： ```swift // 1. user["name"] 返回 Any?（字典值可能不存在） // 2. as? String 尝试将 Any? 转换为 String? // 3. 如果转换失败（nil 或类型不匹配），整个 guard 失败 // 4. 执行 else 块，提前退出函数 ``` **可能失败的情况**： ```swift let testCases = [ // 情况1：字段不存在 ["user": ["age": 25]], // user["name"] 返回 nil // 情况2：类型不匹配 ["user": ["name": 123]], // 123 as? String 返回 nil // 情况3：嵌套字段缺失 ["user": "not a dict"], // user 不是字典类型 // 情况4：成功情况 ["user": ["name": "Alice"]] // 成功转换为 "Alice" ] ``` **为什么用 guard let 而不是 if let？** ```swift // ❌ 使用 if let 会让代码嵌套过深 private func b64urlBad(_ data: Data?) -> String { if let d = data { return d.base64EncodedString() .replacingOccurrences(of: "+", with: "-") .replacingOccurrences(of: "/", with: "_") .replacingOccurrences(of: "=", with: "") } else { return "" } } // ✅ guard let 让主逻辑保持在最外层，更清晰 private func b64urlGood(_ data: Data?) -> String { guard let d = data else { return "" // 提前退出，处理异常情况 } // 主要逻辑在最外层，易读易维护 return d.base64EncodedString() .replacingOccurrences(of: "+", with: "-") .replacingOccurrences(of: "/", with: "_") .replacingOccurrences(of: "=", with: "") } ``` #### 多重 guard 的优势 ```swift // ❌ 嵌套 if let（可读性差） func badParseOptions(_ data: Data, _ cb: @escaping (String) -> Void) { if let pub = try? JSONSerialization.jsonObject(with: data) as? [String: Any] { if let rp = pub["rp"] as? [String: Any] { if let rpId = rp["id"] as? String { if let user = pub["user"] as? [String: Any] { if let userName = user["name"] as? String { // 主逻辑深度嵌套，难以阅读 processData(rpId: rpId, userName: userName) } else { cb(errorJSON) } } else { cb(errorJSON) } } else { cb(errorJSON) } } else { cb(errorJSON) } } else { cb(errorJSON) } } // ✅ 多重 guard let（清晰简洁） func goodParseOptions(_ data: Data, _ cb: @escaping (String) -> Void) { guard let pub = try? JSONSerialization.jsonObject(with: data) as? [String: Any], let rp = pub["rp"] as? [String: Any], let rpId = rp["id"] as? String, let user = pub["user"] as? [String: Any], let userName = user["name"] as? String else { cb(toJSON(["ok": false, "errMsg": "bad options"])) return } // 主逻辑在最外层，清晰易读 processData(rpId: rpId, userName: userName) } ``` #### 实际应用：WebAuthn 数据解析 ```swift // 真实的 WebAuthn 选项解析 func parseWebAuthnOptions(_ optionsJson: String, _ callback: @escaping (String) -> Void) { guard let data = optionsJson.data(using: .utf8) else { callback(errorResponse("Invalid JSON string")) return } guard // 第一层：JSON 解析 let options = try? JSONSerialization.jsonObject(with: data) as? [String: Any], // 第二层：必需字段提取 let rp = options["rp"] as? [String: Any], let rpId = rp["id"] as? String, let rpName = rp["name"] as? String, // 第三层：用户信息提取 let user = options["user"] as? [String: Any], let userIdB64 = user["id"] as? String, let userName = user["name"] as? String, let userDisplayName = user["displayName"] as? String, // 第四层：挑战码和其他参数 let challengeB64 = options["challenge"] as? String, let pubKeyCredParams = options["pubKeyCredParams"] as? [[String: Any]] else { callback(errorResponse("Missing required fields")) return } // 所有必需数据都已成功提取，继续处理 createPasskey(rpId: rpId, rpName: rpName, userId: userIdB64, userName: userName, challenge: challengeB64, params: pubKeyCredParams) } ``` ### 4. 默认值（?? 运算符） ```swift let nickname: String? = nil print(nickname ?? "Guest") // Guest ``` ## 隐式解包（!） 如果一个变量在生命周期内 **一定会有值**，可以用 `String!`： ```swift var username: String! = "Eve" print(username) // 自动解包 → Eve ``` ⚠️ 一般少用，容易出错。 ## 可选链（Optional Chaining） 访问可能为空的属性/方法时，可以用 `?.`： ```swift class Person { var pet: Pet? } class Pet { var name: String = "Dog" } let p = Person() print(p.pet?.name) // nil ``` ### 可选调用操作符（?.）的实战应用 ```swift // 可选方法调用 class AuthManager { private var callback: ((String) -> Void)? func setCallback(_ cb: @escaping (String) -> Void) { self.callback = cb } func triggerSuccess() { // 使用 ?. 安全调用可选的闭包 self.callback?("认证成功") // 等价于： // if let callback = self.callback { // callback("认证成功") // } } func handleError(_ error: Error) { defer { self.callback = nil // 清理回调 } // 可选调用：如果 callback 不为 nil 才执行 self.callback?(toJSON(["ok": false, "errMsg": error.localizedDescription])) } } ``` #### ?. 与 ! 的对比 ```swift let manager = AuthManager() // ❌ 强制调用 - 如果 callback 为 nil 会崩溃 // manager.callback!("消息") // 危险！ // ✅ 可选调用 - 安全，callback 为 nil 时什么都不做 manager.callback?("消息") // 安全 ``` #### 复杂的可选链调用 ```swift class User { var profile: Profile? } class Profile { var settings: Settings? } class Settings { func updateTheme(_ theme: String) { print("主题更新为: \(theme)") } } let user = User() // 多层可选链调用 user.profile?.settings?.updateTheme("暗黑模式") // 只有当 user.profile 和 settings 都不为 nil 时才会执行 // 等价的完整写法： if let profile = user.profile, let settings = profile.settings { settings.updateTheme("暗黑模式") } ``` #### 实际应用场景 ```swift // 1. UI 更新 class ViewController { weak var delegate: ViewControllerDelegate? func viewDidAppear() { // 可选调用 delegate 方法 delegate?.viewControllerDidAppear(self) } } // 2. 网络回调 class NetworkManager { var onComplete: ((Data?) -> Void)? var onError: ((Error) -> Void)? func performRequest() { URLSession.shared.dataTask(with: url) { data, response, error in if let error = error { self.onError?(error) // 可选调用错误回调 } else { self.onComplete?(data) // 可选调用成功回调 } }.resume() } } // 3. 系统 API 回调（你的代码应用） public func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) { defer { self.callback = nil } // 可选调用：只有当 callback 存在时才执行 self.callback?(self.toJSON(["ok": false, "errMsg": error.localizedDescription])) // 如果不用 ?.，需要这样写： // if let callback = self.callback { // callback(self.toJSON(["ok": false, "errMsg": error.localizedDescription])) // } } ``` ## 实战示例：JSON 处理中的空安全 ### try? 与可选绑定的组合 ```swift // 将字典转换为 JSON 字符串的安全写法 func dictToJSON(_ dict: [String: Any]) -> String { if let data = try? JSONSerialization.data(withJSONObject: dict, options: []) { return String(data: data, encoding: .utf8) ?? "{}" } return "{}" } // 使用示例 let userInfo = ["name": "Alice", "age": 25] let jsonString = dictToJSON(userInfo) print(jsonString) // {"name":"Alice","age":25} ``` ### try? 与 as? 的双重安全 ```swift // JSON 反序列化：Data → 字典 func parseJSON(_ data: Data) -> [String: Any]? { let pub = try? JSONSerialization.jsonObject(with: data) as? [String: Any] return pub } // 完整示例 let jsonData = """ { "name": "Alice", "age": 25, "active": true } """.data(using: .utf8)! if let dict = parseJSON(jsonData) { print("姓名: \(dict["name"] ?? "未知")") print("年龄: \(dict["age"] ?? 0)") } ``` #### 语法分解：try? as? ```swift let pub = try? JSONSerialization.jsonObject(with: data) as? [String: Any] // ↑ ↑ // try? as? // 错误处理 类型转换 ``` **第一层安全：try?** ```swift // JSONSerialization.jsonObject 可能抛出错误 // try? 将错误转换为 nil // 等价于： let jsonObject: Any? do { jsonObject = try JSONSerialization.jsonObject(with: data) } catch { jsonObject = nil } ``` **第二层安全：as?** ```swift // jsonObject 的类型是 Any，需要转换为 [String: Any] // as? 安全类型转换，失败返回 nil // 等价于： let dict: [String: Any]? if jsonObject is [String: Any] { dict = jsonObject as! [String: Any] } else { dict = nil } ``` #### 组合使用的优势 ```swift // ❌ 不安全的写法（可能崩溃） func badParseJSON(_ data: Data) -> [String: Any] { let obj = try! JSONSerialization.jsonObject(with: data) // 可能抛出异常 return obj as! [String: Any] // 可能类型转换失败 } // ✅ 安全的写法（双重保护） func safeParseJSON(_ data: Data) -> [String: Any]? { return try? JSONSerialization.jsonObject(with: data) as? [String: Any] // 1. try? 处理 JSON 解析错误 // 2. as? 处理类型转换失败 } // ✅ 更详细的错误处理 func detailedParseJSON(_ data: Data) -> [String: Any]? { guard let jsonObject = try? JSONSerialization.jsonObject(with: data) else { print("JSON 解析失败") return nil } guard let dict = jsonObject as? [String: Any] else { print("类型转换失败，期望字典类型") return nil } return dict } ``` #### 实际应用场景 ```swift // 网络请求中的 JSON 处理 func handleAPIResponse(_ data: Data) { if let response = try? JSONSerialization.jsonObject(with: data) as? [String: Any] { // 成功解析为字典 let status = response["status"] as? String ?? "unknown" let message = response["message"] as? String ?? "" print("状态: \(status), 消息: \(message)") } else { print("响应格式错误") } } // 配置文件解析 func loadConfig(_ data: Data) -> AppConfig? { guard let configDict = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return nil } return AppConfig( apiURL: configDict["apiURL"] as? String ?? "", timeout: configDict["timeout"] as? Double ?? 30.0, enableLogging: configDict["enableLogging"] as? Bool ?? false ) } // WebAuthn 数据解析 func parsePasskeyOptions(_ data: Data) -> PasskeyOptions? { guard let optionsDict = try? JSONSerialization.jsonObject(with: data) as? [String: Any], let rp = optionsDict["rp"] as? [String: Any], let user = optionsDict["user"] as? [String: Any] else { return nil } return PasskeyOptions( rpId: rp["id"] as? String ?? "", userName: user["name"] as? String ?? "", challenge: optionsDict["challenge"] as? String ?? "" ) } ``` 让我们分解这段代码的每个部分： ### 1. try? 的作用 ```swift // JSONSerialization.data 可能抛出错误 // try? 将错误转换为 nil，返回 Optional let data = try? JSONSerialization.data(withJSONObject: dict, options: []) // data 的类型是 Data?（可选类型） ``` ### 2. if let 安全解包 ```swift if let data = try? JSONSerialization.data(withJSONObject: dict, options: []) { // 只有 data 不为 nil 时才执行这里 // data 在这个作用域内是 Data 类型（已解包） } ``` ### 3. 双重保险的默认值 ```swift // String(data:encoding:) 也可能返回 nil // 第一层保险：?? "{}" return String(data: data, encoding: .utf8) ?? "{}" // 第二层保险：整个 if let 失败时 return "{}" ``` ### 4. 完整的错误处理对比 ```swift // ❌ 不安全的写法 func badDictToJSON(_ dict: [String: Any]) -> String { let data = try! JSONSerialization.data(withJSONObject: dict, options: []) return String(data: data, encoding: .utf8)! // 可能崩溃 } // ✅ 安全的写法 func safeDictToJSON(_ dict: [String: Any]) -> String { guard let data = try? JSONSerialization.data(withJSONObject: dict, options: []), let jsonString = String(data: data, encoding: .utf8) else { return "{}" // 任何步骤失败都返回默认值 } return jsonString } // ✅ 更简洁的写法（你的代码） func conciseDictToJSON(_ dict: [String: Any]) -> String { if let data = try? JSONSerialization.data(withJSONObject: dict, options: []) { return String(data: data, encoding: .utf8) ?? "{}" } return "{}" } ``` ### 5. 实际使用场景 ```swift // 网络请求中的 JSON 处理 class APIClient { func sendRequest(_ params: [String: Any]) { let jsonString = dictToJSON(params) // 即使 params 有问题，也不会崩溃，最多发送空对象 "{}" print("发送数据: \(jsonString)") } } // 日志记录 func logUserAction(_ action: String, data: [String: Any]) { let jsonData = dictToJSON(data) print("[\(action)] \(jsonData)") // 保证日志一定能记录，不会因为 JSON 转换失败而中断 } ``` ## 小结 - `?` → 表示可能为空。 - `!` → 强制解包，危险。 - `if let` / `guard let` → 安全解包。 - `??` → 提供默认值。 - `?.` → 可选链，优雅避免空指针。 - `try?` → 将错误转换为可选类型，配合 `if let` 使用。 ]]> http://herong.info/posts/swift-quickstart/07-字符串与日期 http://herong.info/posts/swift-quickstart/07-字符串与日期 Sun, 14 Sep 2025 00:00:00 GMT 字符串和日期是开发中最常用的数据类型。Swift 提供了强大且安全的操作方式。 ## 字符串（String） ### 创建字符串 ```swift let s1 = "Hello" let s2 = String("World") ``` ### 拼接 ```swift let name = "Alice" let greeting = "Hello, " + name print(greeting) // Hello, Alice ``` ### 字符串插值 ```swift let age = 20 print("My age is \(age)") // My age is 20 ``` ### 遍历字符 ```swift for ch in "Swift" { print(ch) } ``` ### 字符串长度 ```swift let text = "Hello" print(text.count) // 5 ``` ### 子串 ```swift let str = "Hello Swift" let start = str.startIndex let end = str.index(str.startIndex, offsetBy: 4) let sub = str[start...end] print(sub) // Hello ``` ### 常用方法 ```swift let msg = " swift " print(msg.uppercased()) // " SWIFT " print(msg.lowercased()) // " swift " print(msg.trimmingCharacters(in: .whitespaces)) // "swift" print(msg.contains("sw")) // true ``` ### 字符串替换与链式调用 #### replacingOccurrences 方法 ```swift // 单个替换 let text = "Hello World" let newText = text.replacingOccurrences(of: " ", with: "-") print(newText) // "Hello-World" // 多个替换的链式调用 let original = "a+b/c=d" let result = original .replacingOccurrences(of: "+", with: "-") .replacingOccurrences(of: "/", with: "_") .replacingOccurrences(of: "=", with: "") print(result) // "a-b_cd" ``` #### 什么是 Data 类型？ `Data` 是 Swift Foundation 框架中的核心类型，用于表示**二进制数据**。 ```swift import Foundation // Data 来自 Foundation 框架 // Data 的本质：字节数组 let data1 = Data([0x48, 0x65, 0x6C, 0x6C, 0x6F]) // "Hello" 的字节表示 print(data1) // 5 bytes // 常见的 Data 创建方式 let data2 = "Hello".data(using: .utf8)! // 字符串 → Data let data3 = Data(count: 10) // 创建 10 字节的空 Data let data4 = Data(base64Encoded: "SGVsbG8=")! // Base64 → Data ``` #### Data 的来源和用途 | 来源 | 方法 | 用途 | | ----------- | --------------------------- | ---------------- | | 字符串转换 | `"text".data(using: .utf8)` | 文本数据处理 | | 网络请求 | `URLSession` 响应 | API 数据接收 | | 文件读取 | `Data(contentsOf: url)` | 文件内容读取 | | 图片处理 | `UIImage.pngData()` | 图片数据转换 | | JSON 序列化 | `JSONSerialization.data()` | 对象 → JSON 数据 | #### 实战：Base64URL 编码转换 ```swift // 完整的 Data → Base64URL 流程 func dataToBase64URL(_ data: Data) -> String { // 1. Data → 标准 Base64 字符串 var s = data.base64EncodedString() // 2. 标准 Base64 → Base64URL s = s.replacingOccurrences(of: "+", with: "-") .replacingOccurrences(of: "/", with: "_") .replacingOccurrences(of: "=", with: "") return s } // 使用示例 let textData = "Hello World".data(using: .utf8)! let base64url = dataToBase64URL(textData) print(base64url) // "SGVsbG8gV29ybGQ" // 更简洁的写法（一行完成） return data.base64EncodedString() .replacingOccurrences(of: "+", with: "-") .replacingOccurrences(of: "/", with: "_") .replacingOccurrences(of: "=", with: "") ``` #### 反向转换：Base64URL → Data ```swift // Base64URL 解码函数 func base64URLToData(_ s: String) -> Data { // 1. Base64URL → 标准 Base64 var t = s.replacingOccurrences(of: "-", with: "+") // - → + .replacingOccurrences(of: "_", with: "/") // _ → / // 2. 计算并添加填充字符 let pad = (4 - t.count % 4) % 4 // 计算需要多少个 = 填充 if pad > 0 { t.append(String(repeating: "=", count: pad)) // 添加 = 填充 } // 3. 标准 Base64 → Data return Data(base64Encoded: t) ?? Data() } ``` #### 数据转换过程详解 **完整的双向转换流程：** ```swift // 原始数据 let originalText = "Hello World!" let originalData = originalText.data(using: .utf8)! print("原始数据: \(originalText)") // "Hello World!" // 第一步：Data → Base64URL let base64url = originalData.base64EncodedString() .replacingOccurrences(of: "+", with: "-") .replacingOccurrences(of: "/", with: "_") .replacingOccurrences(of: "=", with: "") print("Base64URL: \(base64url)") // "SGVsbG8gV29ybGQh" // 第二步：Base64URL → Data（你的代码） let decodedData = base64URLToData(base64url) let decodedText = String(data: decodedData, encoding: .utf8)! print("解码结果: \(decodedText)") // "Hello World!" ``` #### 填充计算逻辑解析 Base64 编码要求长度是 4 的倍数，不足时用 `=` 填充： ```swift // 填充计算公式：(4 - length % 4) % 4 let examples = [ ("SGVsbG8", 7), // 7 % 4 = 3, 需要 1 个 = ("SGVsbG8g", 8), // 8 % 4 = 0, 不需要填充 ("SGVsbG8gV2", 10), // 10 % 4 = 2, 需要 2 个 = ] for (base64url, length) in examples { let pad = (4 - length % 4) % 4 let padded = pad > 0 ? base64url + String(repeating: "=", count: pad) : base64url print("\(base64url) → \(padded) (添加 \(pad) 个 =)") } // 输出： // SGVsbG8 → SGVsbG8= (添加 1 个 =) // SGVsbG8g → SGVsbG8g (添加 0 个 =) // SGVsbG8gV2 → SGVsbG8gV2== (添加 2 个 =) ``` #### 实际应用：JWT Token 解析 ```swift // JWT Token 通常使用 Base64URL 编码 func decodeJWTPayload(_ token: String) -> [String: Any]? { let parts = token.components(separatedBy: ".") guard parts.count == 3 else { return nil } // 解码 payload 部分（第二部分） let payloadData = base64URLToData(parts[1]) // JSON 解析 return try? JSONSerialization.jsonObject(with: payloadData) as? [String: Any] } // WebAuthn 挑战码解析 func decodeChallenge(_ challengeString: String) -> Data { return base64URLToData(challengeString) } ``` #### Data 的常用方法 ```swift let data = "Hello".data(using: .utf8)! // 基本属性 print(data.count) // 5 (字节数) print(data.isEmpty) // false // 转换方法 let string = String(data: data, encoding: .utf8) // Data → 字符串 let base64 = data.base64EncodedString() // Data → Base64 let array = [UInt8](data) // Data → 字节数组 // 操作方法 var mutableData = data mutableData.append("!".data(using: .utf8)!) // 追加数据 print(String(data: mutableData, encoding: .utf8)!) // "Hello!" ``` #### 方法解析表 | 方法 | 作用 | 示例 | | -------------------------------- | -------------------- | ---------------------- | | `base64EncodedString()` | Data → Base64 字符串 | `"SGVsbG8="` | | `replacingOccurrences(of:with:)` | 替换所有匹配的子串 | `"a+b" → "a-b"` | | 链式调用 | 多个方法连续执行 | `.method1().method2()` | #### Base64 vs Base64URL 对比 ```swift let data = "Hello World".data(using: .utf8)! // 标准 Base64 let base64 = data.base64EncodedString() print(base64) // "SGVsbG8gV29ybGQ=" // Base64URL（URL 安全） let base64url = data.base64EncodedString() .replacingOccurrences(of: "+", with: "-") // + → - .replacingOccurrences(of: "/", with: "_") // / → _ .replacingOccurrences(of: "=", with: "") // 移除填充 print(base64url) // "SGVsbG8gV29ybGQ" ``` #### 为什么需要 Base64URL？ ```swift // ❌ 标准 Base64 在 URL 中会有问题 let url1 = "https://api.com/token=SGVsbG8+V29/bGQ=" // + 和 / 在 URL 中有特殊含义 // ✅ Base64URL 是 URL 安全的 let url2 = "https://api.com/token=SGVsbG8-V29_bGQ" // - 和 _ 在 URL 中安全 ``` #### 实际应用场景 ```swift // JWT Token 编码 func encodeJWTPayload(_ payload: [String: Any]) -> String { guard let data = try? JSONSerialization.data(withJSONObject: payload) else { return "" } return data.base64EncodedString() .replacingOccurrences(of: "+", with: "-") .replacingOccurrences(of: "/", with: "_") .replacingOccurrences(of: "=", with: "") } // WebAuthn 挑战码处理 func processChallenge(_ challengeData: Data) -> String { return challengeData.base64EncodedString() .replacingOccurrences(of: "+", with: "-") .replacingOccurrences(of: "/", with: "_") .trimmingCharacters(in: CharacterSet(charactersIn: "=")) } ``` ## 日期（Date） ### 当前时间 ```swift let now = Date() print(now) // 2025-09-14 12:34:56 +0000 ``` ### 日期格式化 ```swift let formatter = DateFormatter() formatter.dateFormat = "yyyy-MM-dd HH:mm:ss" let now = Date() let str = formatter.string(from: now) print(str) // 2025-09-14 20:34:56 ``` ### 字符串转日期 ```swift let formatter = DateFormatter() formatter.dateFormat = "yyyy/MM/dd" if let date = formatter.date(from: "2025/09/14") { print(date) } ``` ### 日期计算 ```swift let now = Date() let tomorrow = now.addingTimeInterval(24 * 60 * 60) print(tomorrow) ``` ## 小结 - **字符串**：拼接 `+`，插值 `\(var)`，常用方法 `uppercased`、`contains`、`trimmingCharacters`。 - **日期**：`Date()` 获取当前时间，`DateFormatter` 用于格式化和解析。 ]]> http://herong.info/posts/swift-quickstart/08-闭包 http://herong.info/posts/swift-quickstart/08-闭包 Sun, 14 Sep 2025 00:00:00 GMT 闭包（Closure）是 Swift 的核心特性之一，类似匿名函数。它能捕获上下文变量，非常常用。 ## 基本语法 闭包的基本形式： ```swift { (参数列表) -> 返回类型 in 代码块 } ``` 例如： ```swift let add = { (a: Int, b: Int) -> Int in return a + b } print(add(2, 3)) // 5 ``` ## 作为函数参数 ```swift func operate(_ a: Int, _ b: Int, op: (Int, Int) -> Int) -> Int { return op(a, b) } let sum = operate(2, 3, op: { (x, y) in x + y }) print(sum) // 5 ``` ## 闭包简写 Swift 提供了简写规则，使闭包更简洁： 1. **省略参数类型和返回值** 2. **省略 return** 3. **使用参数占位符 `$0`, `$1`** ```swift let nums = [3, 1, 5, 2] let sorted = nums.sorted(by: { $0 < $1 }) print(sorted) // [1, 2, 3, 5] ``` ## 尾随闭包 当闭包是函数最后一个参数时，可以写在括号外： ```swift let doubled = nums.map { $0 * 2 } print(doubled) // [6, 2, 10, 4] ``` ## 捕获变量 闭包会捕获外部变量： ```swift func makeCounter() -> () -> Int { var count = 0 return { count += 1 return count } } let counter = makeCounter() print(counter()) // 1 print(counter()) // 2 ``` ## 常见应用场景 1. **数组操作（map/filter/reduce）** 2. **回调（网络请求完成后执行）** 3. **延迟执行** ## 实战：first(where:) 方法 ### 基础用法 ```swift let numbers = [1, 3, 5, 7, 8, 9] // 完整闭包语法 let firstEven = numbers.first(where: { (number) -> Bool in return number % 2 == 0 }) print(firstEven) // Optional(8) // 简化语法 let firstOdd = numbers.first { $0 % 2 == 1 } print(firstOdd) // Optional(1) ``` ### 实际项目中的应用：寻找活跃窗口 ```swift // 在 iOS 应用中寻找当前活跃的窗口 public func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor { return UIApplication.shared.windows.first { $0.isKeyWindow // 尾随闭包：寻找 isKeyWindow 为 true 的窗口 } ?? ASPresentationAnchor() } ``` #### 语法分解 ```swift // 1. 完整写法 UIApplication.shared.windows.first(where: { window in return window.isKeyWindow }) // 2. 省略参数类型和 return UIApplication.shared.windows.first(where: { window in window.isKeyWindow }) // 3. 使用参数占位符 UIApplication.shared.windows.first(where: { $0.isKeyWindow }) // 4. 尾随闭包语法（最简洁） UIApplication.shared.windows.first { $0.isKeyWindow } ``` #### 更多 first(where:) 实战示例 ```swift // 寻找特定用户 let users = [ User(name: "Alice", age: 25), User(name: "Bob", age: 30), User(name: "Charlie", age: 35) ] let adult = users.first { $0.age >= 18 } let alice = users.first { $0.name == "Alice" } // 寻找特定视图控制器 let viewControllers = navigationController?.viewControllers ?? [] let targetVC = viewControllers.first { $0 is SettingsViewController } // 寻找有效的网络配置 let configs = [config1, config2, config3] let validConfig = configs.first { $0.isValid && $0.isEnabled } ``` ### 与其他高阶函数的对比 ```swift let data = [1, 2, 3, 4, 5] // first(where:) - 找到第一个符合条件的元素 let firstEven = data.first { $0 % 2 == 0 } // Optional(2) // filter - 找到所有符合条件的元素 let allEvens = data.filter { $0 % 2 == 0 } // [2, 4] // contains(where:) - 判断是否存在符合条件的元素 let hasEven = data.contains { $0 % 2 == 0 } // true // firstIndex(where:) - 找到第一个符合条件的元素的索引 let index = data.firstIndex { $0 % 2 == 0 } // Optional(1) ``` ## @escaping 闭包详解 ### 什么是 @escaping？ ```swift // 非逃逸闭包（默认）- 函数返回前必须执行 func processData(_ data: String, completion: (String) -> Void) { let result = data.uppercased() completion(result) // 在函数返回前执行 } // 逃逸闭包 - 可能在函数返回后执行 func processDataAsync(_ data: String, completion: @escaping (String) -> Void) { DispatchQueue.global().async { let result = data.uppercased() completion(result) // 在函数返回后执行 } } ``` ### 实战：@objc 方法中的回调 ```swift @objc public func register(_ optionsJson: String, _ cb: @escaping (String) -> Void) { // 这个回调会在异步操作完成后执行，所以需要 @escaping } ``` #### 语法分解 ```swift // 1. @objc - 使方法可被 Objective-C 调用 // 2. public - 外部模块可访问 // 3. _ optionsJson: String - 无标签参数 // 4. _ cb: @escaping (String) -> Void - 逃逸闭包回调 @objc public func register(_ optionsJson: String, _ cb: @escaping (String) -> Void) { // 参数解析 guard let options = parseOptions(optionsJson) else { cb("{\"ok\": false, \"errMsg\": \"Invalid options\"}") return } // 异步认证操作 performAuthentication(options: options) { result in // 这个回调在异步操作完成后执行 cb(result) // 需要 @escaping 才能在这里调用 } } ``` ### 为什么需要 @escaping？ ```swift class AuthManager { private var callback: ((String) -> Void)? // 存储回调 // ❌ 编译错误：非逃逸闭包不能赋值给属性 func badExample(_ completion: (String) -> Void) { self.callback = completion // 错误！ } // ✅ 正确：使用 @escaping func goodExample(_ completion: @escaping (String) -> Void) { self.callback = completion // 正确！ } func triggerCallback() { callback?("操作完成") } } ``` ### 实际应用场景 #### 1. 网络请求回调 ```swift @objc public func fetchUserData(_ userId: String, _ callback: @escaping (String) -> Void) { URLSession.shared.dataTask(with: url) { data, response, error in // 网络请求是异步的，回调在请求完成后执行 if let data = data { callback(String(data: data, encoding: .utf8) ?? "") } else { callback("{\"error\": \"Network failed\"}") } }.resume() } ``` #### 2. 系统认证回调 ```swift @objc public func authenticate(_ options: String, _ callback: @escaping (String) -> Void) { let authController = ASAuthorizationController(authorizationRequests: requests) // 存储回调，在认证完成后调用 self.completionCallback = callback authController.delegate = self authController.performRequests() // 异步操作 } // 在协议方法中调用存储的回调 func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) { completionCallback?("{\"ok\": true, \"data\": \"...\"}") completionCallback = nil } ``` #### 3. 延迟执行 ```swift @objc public func delayedOperation(_ seconds: Double, _ callback: @escaping (String) -> Void) { DispatchQueue.main.asyncAfter(deadline: .now() + seconds) { callback("延迟操作完成") // 在未来某个时间点执行 } } ``` ### 闭包类型语法详解 ```swift // (String) -> Void 的含义： // ↓ // 接收一个 String 参数，无返回值的闭包类型 // 其他常见闭包类型 let closure1: () -> Void = { print("无参数无返回值") } let closure2: (Int) -> String = { "\($0)" } let closure3: (String, Int) -> Bool = { $0.count > $1 } // 在函数参数中使用 func process(_ data: String, success: @escaping (String) -> Void, failure: @escaping (Error) -> Void) { // 成功和失败的不同回调 } ``` ### @escaping vs 非逃逸对比 | 特性 | 非逃逸闭包（默认） | @escaping 闭包 | | ------------ | ------------------ | -------------------- | | **执行时机** | 函数返回前必须执行 | 可在函数返回后执行 | | **存储** | 不能赋值给属性 | 可以赋值给属性 | | **异步操作** | 不支持 | 支持 | | **性能** | 更好（编译器优化） | 稍差（需要内存管理） | | **使用场景** | 同步操作、集合遍历 | 异步操作、回调存储 | ### 实际使用建议 ```swift // ✅ 同步操作用非逃逸闭包 func transform(_ items: [T], _ transform: (T) -> T) -> [T] { return items.map(transform) // 立即执行 } // ✅ 异步操作用 @escaping func loadData(_ completion: @escaping (Data?) -> Void) { DispatchQueue.global().async { // 异步加载数据 completion(data) } } // ✅ 需要存储回调用 @escaping class APIClient { private var onComplete: ((String) -> Void)? func request(_ callback: @escaping (String) -> Void) { self.onComplete = callback // 存储以备后用 } } ``` ## 小结 - 闭包 = 匿名函数，可以捕获外部变量。 - 语法简洁，支持尾随闭包。 - `@escaping` 用于可能在函数返回后执行的闭包。 - 异步操作、回调存储都需要 `@escaping`。 - 常用于集合操作、网络请求和系统 API 回调。 ]]> http://herong.info/posts/swift-quickstart/09-结构体与类 http://herong.info/posts/swift-quickstart/09-结构体与类 Sun, 14 Sep 2025 00:00:00 GMT Swift 中既有 **结构体（struct）**，也有 **类（class）**。两者非常相似，但也有重要区别。 ## 定义结构体 ```swift struct Point { var x: Int var y: Int } var p1 = Point(x: 3, y: 5) p1.x = 10 print(p1) // Point(x: 10, y: 5) ``` 结构体自动拥有一个 **成员初始化器**，不需要手动写构造函数。 ## 定义类 ```swift class Person { var name: String var age: Int init(name: String, age: Int) { self.name = name self.age = age } } let p = Person(name: "Tom", age: 20) print(p.name) // Tom ``` 类需要写 `init` 构造函数来初始化属性。 ## 值类型 vs 引用类型 这是两者最大的区别： - **结构体** 是 **值类型**，赋值时会复制一份。 - **类** 是 **引用类型**，赋值时多个变量指向同一个对象。 ```swift var a = Point(x: 1, y: 2) var b = a b.x = 100 print(a.x) // 1（不受影响） let p2 = p p2.name = "Jerry" print(p.name) // Jerry（引用同一个对象） ``` ## 选择结构体还是类？ - **结构体**：推荐默认使用，轻量、安全，常用于数据模型。 - **类**：当需要继承、引用语义时使用（如视图控制器）。 ## 类的高级用法 ### 继承与协议实现 ```swift // 继承系统类并实现协议的语法 class PasskeysNative: NSObject, ASAuthorizationControllerDelegate { // 类的内容 } ``` 语法结构：`class 类名: 父类, 协议1, 协议2, ...` ### 为什么继承 NSObject？ ```swift // ✅ 继承 NSObject 的好处 class MyClass: NSObject { // 1. 与 Objective-C 兼容 // 2. 支持 @objc 标记的方法 // 3. 可以被跨语言框架调用 // 4. 支持 KVO、KVC 等特性 } // ❌ 纯 Swift 类的限制 class PureSwiftClass { // 无法直接与 Objective-C 交互 } ``` ### 实现协议方法 ```swift class AuthHandler: NSObject, SomeProtocol { // 实现协议要求的方法 func requiredMethod() { print("实现协议方法") } } ``` ## 小结 - `struct` = 值类型，复制独立。 - `class` = 引用类型，共享同一对象。 - 类可以继承父类并实现多个协议。 - 继承 `NSObject` 提供 Objective-C 兼容性。 - Swift 鼓励多用结构体，少用类，除非需要继承。 ]]> http://herong.info/posts/swift-quickstart/10-属性与方法 http://herong.info/posts/swift-quickstart/10-属性与方法 Sun, 14 Sep 2025 00:00:00 GMT Swift 中，结构体和类可以有 **属性（properties）** 和 **方法（methods）**，这是面向对象编程的核心。 ## 存储属性 直接存储值在实例里的属性。 ```swift struct User { var name: String var age: Int } var u = User(name: "Tom", age: 20) u.age = 21 print(u.age) // 21 ``` ## 计算属性 不会直接存储值，而是通过 getter/setter 计算得到。 ```swift struct Rectangle { var width: Double var height: Double var area: Double { return width * height } } let r = Rectangle(width: 5, height: 3) print(r.area) // 15.0 ``` ## 属性观察器 在属性变化时触发 `willSet` / `didSet`。 ```swift class Counter { var count: Int = 0 { willSet { print("即将设置为 \(newValue)") } didSet { print("已从 \(oldValue) 改为 \(count)") } } } let c = Counter() c.count = 5 // 即将设置为 5 // 已从 0 改为 5 ``` ## 方法 方法就是定义在类/结构体中的函数。 ```swift struct Circle { var radius: Double func area() -> Double { return 3.14 * radius * radius } } let c1 = Circle(radius: 10) print(c1.area()) // 314.0 ``` ## mutating 方法 结构体是 **值类型**，默认方法不能修改属性。需要 `mutating` 关键字。 ```swift struct Counter { var value = 0 mutating func increment() { value += 1 } } var ct = Counter() ct.increment() print(ct.value) // 1 ``` ## 静态属性和方法 属于类型本身，而不是某个实例。 ```swift struct Math { static let pi = 3.14159 static func square(_ x: Int) -> Int { return x * x } } print(Math.pi) // 3.14159 print(Math.square(5)) // 25 ``` ## 小结 - **存储属性**：保存值。 - **计算属性**：动态计算。 - **属性观察器**：监听变化。 - **实例方法**：作用于实例。 - **mutating 方法**：修改结构体/枚举。 - **静态属性/方法**：属于类型。 ]]> http://herong.info/posts/swift-quickstart/11-枚举 http://herong.info/posts/swift-quickstart/11-枚举 Sun, 14 Sep 2025 00:00:00 GMT 枚举（`enum`）是 Swift 中非常常见的语法结构，用来表示一组有限的、相关的值。 > 它比许多其他语言中的枚举更强大，支持关联值、原始值，还能扩展方法。 ## 1. 基本用法 ```swift enum Direction { case north case south case east case west } let d = Direction.north print(d) // north ``` 你也可以写在一行： ```swift enum Direction { case north, south, east, west } ``` ## 2. 搭配 switch 使用 ```swift func move(_ dir: Direction) { switch dir { case .north: print("向北走") case .south: print("向南走") case .east: print("向东走") case .west: print("向西走") } } move(.east) // 向东走 ``` > `switch` 必须覆盖所有枚举的情况，否则编译报错。 ## 3. 枚举的原始值 枚举的每个 case 可以绑定一个 **原始值**（Raw Value），常见于数字或字符串。 ```swift enum Weekday: Int { case monday = 1, tuesday, wednesday, thursday, friday, saturday, sunday } print(Weekday.friday.rawValue) // 5 if let day = Weekday(rawValue: 7) { print(day) // sunday } ``` ## 4. 枚举的关联值 有时 case 需要携带不同的数据，这时可以用 **关联值**。 ```swift enum LoginState { case success(user: String) case failure(error: String) } let result = LoginState.success(user: "Alice") switch result { case .success(let user): print("登录成功：\(user)") case .failure(let error): print("失败：\(error)") } ``` ## 5. 枚举的方法 枚举可以像类和结构体一样添加方法。 ```swift enum TrafficLight { case red, yellow, green func action() -> String { switch self { case .red: return "停" case .yellow: return "等" case .green: return "走" } } } print(TrafficLight.green.action()) // 走 ``` ## 总结 - `enum` 用来表示有限集合。 - 搭配 `switch` 使用非常常见。 - 可以有 **原始值** 和 **关联值**。 - 可以定义 **方法**，功能接近类和结构体。 Swift 的枚举很灵活，不只是常量集合，更像“轻量的数据类型”。 ]]> http://herong.info/posts/swift-quickstart/12-协议 http://herong.info/posts/swift-quickstart/12-协议 Sun, 14 Sep 2025 00:00:00 GMT 协议（`protocol`）就像“契约”，规定了 **必须具备的属性和方法**。 > 类、结构体、枚举都可以遵循协议。 ## 1. 定义协议 ```swift protocol Drawable { func draw() } ``` ## 2. 遵循协议 ```swift struct Circle: Drawable { func draw() { print("画一个圆") } } let c = Circle() c.draw() // 画一个圆 ``` ## 3. 属性要求 协议可以要求属性，但只规定 **读/写权限**，不实现。 ```swift protocol Named { var name: String { get set } var description: String { get } } struct Person: Named { var name: String var description: String { "我的名字是 \(name)" } } let p = Person(name: "Alice") print(p.description) // 我的名字是 Alice ``` ## 4. 多协议 一个类型可以同时遵循多个协议。 ```swift protocol Flyable { func fly() } protocol Swimmable { func swim() } struct Duck: Flyable, Swimmable { func fly() { print("鸭子会飞") } func swim() { print("鸭子会游泳") } } ``` ## 5. 协议作为类型 协议不仅是规范，也能作为类型使用。 ```swift func test(d: Drawable) { d.draw() } test(d: Circle()) // 画一个圆 ``` ## 6. 协议继承 协议可以继承其它协议。 ```swift protocol Animal { func eat() } protocol Pet: Animal { func play() } struct Dog: Pet { func eat() { print("狗在吃") } func play() { print("狗在玩") } } ``` ## 7. 实战：系统协议实现 ### AuthenticationServices 协议示例 ````swift import AuthenticationServices class PasskeysManager: NSObject { // 私有属性存储回调 private var callback: ((String) -> Void)? } // 使用 extension 分组实现协议 extension PasskeysManager: ASAuthorizationControllerDelegate { // 认证成功回调 func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) { callback?("认证成功") callback = nil } // 认证失败回调 func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) { callback?("认证失败: \(error.localizedDescription)") callback = nil } } extension PasskeysManager: ASAuthorizationControllerPresentationContextProviding { // 提供展示认证界面的窗口 func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor { return UIApplication.shared.windows.first { $0.isKeyWindow } ?? UIWindow() } } #### 协议方法详解：presentationAnchor ```swift public func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor { return UIApplication.shared.windows.first { $0.isKeyWindow } ?? ASPresentationAnchor() } ```` **这个方法在做什么？** - 为 AuthenticationServices 提供一个"锚点窗口" - 系统会在这个窗口上显示 Face ID/Touch ID 认证界面 #### 语法分解 **1. 方法签名** ```swift // 协议要求的方法签名 func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor ``` **2. 核心逻辑：寻找活跃窗口** ```swift UIApplication.shared.windows.first { $0.isKeyWindow // 尾随闭包语法 } ``` 等价于： ```swift UIApplication.shared.windows.first(where: { window in return window.isKeyWindow }) ``` **3. 类型别名** ```swift // ASPresentationAnchor 实际上就是 UIWindow typealias ASPresentationAnchor = UIWindow ``` #### 不同的实现方式对比 ```swift // ✅ 你的实现：安全的空窗口降级 func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor { return UIApplication.shared.windows.first { $0.isKeyWindow } ?? ASPresentationAnchor() } // ✅ 常见实现：返回空 UIWindow func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor { return UIApplication.shared.windows.first { $0.isKeyWindow } ?? UIWindow() } // ✅ iOS 13+ 现代写法 func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor { return view.window ?? UIWindow() } // ❌ 不安全的写法（可能崩溃） func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor { return UIApplication.shared.windows.first { $0.isKeyWindow }! // 强制解包危险 } ``` #### 实际应用场景 ```swift class PasskeysViewController: UIViewController { private let passkeysManager = PasskeysManager() override func viewDidLoad() { super.viewDidLoad() // 当用户点击认证按钮时 let authController = ASAuthorizationController(authorizationRequests: [/* ... */]) authController.delegate = passkeysManager authController.presentationContextProvider = passkeysManager // 👈 会调用 presentationAnchor authController.performRequests() } } ``` #### 为什么需要这个方法？ 1. **系统需要知道在哪个窗口显示认证界面** 2. **确保认证界面显示在正确的屏幕上**（多屏设备） 3. **处理应用的窗口层级关系** #### 常见问题和解决方案 ```swift // 问题：iOS 13+ 中 windows 数组可能为空 // 解决：使用 scene-based 方法 @available(iOS 13.0, *) func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor { if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene { return windowScene.windows.first { $0.isKeyWindow } ?? UIWindow() } return UIWindow() } // 问题：SwiftUI 环境中的处理 func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor { return UIApplication.shared.windows.first { $0.isKeyWindow } ?? UIApplication.shared.windows.first ?? UIWindow() } ``` ```` ### @objc 协议兼容 ```swift // 跨语言调用的协议设计 @objc public protocol AuthenticationAPI { func register(_ options: String, callback: @escaping (String) -> Void) func authenticate(_ options: String, callback: @escaping (String) -> Void) } @objc public class AuthManager: NSObject, AuthenticationAPI { @objc public func register(_ options: String, callback: @escaping (String) -> Void) { // 实现注册逻辑 callback("注册成功") } @objc public func authenticate(_ options: String, callback: @escaping (String) -> Void) { // 实现认证逻辑 callback("认证成功") } } ```` ### 协议实现的最佳实践 ```swift // ✅ 使用 extension 分组组织协议实现 extension MyClass: ProtocolA { // ProtocolA 的方法 } extension MyClass: ProtocolB { // ProtocolB 的方法 } // ✅ 使用 MARK 注释分组 class MyClass { // MARK: - ProtocolA Implementation // MARK: - ProtocolB Implementation } ``` ## 总结 - `protocol` 用来定义 **方法和属性的规范**。 - 类/结构体/枚举都可以遵循协议。 - 协议也可以 **继承** 和 **组合**。 - 使用 `extension` 分组实现协议方法，代码更清晰。 - `@objc` 协议支持跨语言调用。 - 协议能作为类型使用，是 Swift 面向协议编程的基础。 ]]> http://herong.info/posts/swift-quickstart/13-扩展 http://herong.info/posts/swift-quickstart/13-扩展 Sun, 14 Sep 2025 00:00:00 GMT **扩展（`extension`）** 可以给已有的类、结构体、枚举、协议 **添加新功能**，而无需修改原有代码。 > 这在实际开发中非常常用。 ## 1. 给已有类型添加方法 ```swift extension Int { func squared() -> Int { return self * self } } print(5.squared()) // 25 ``` ## 2. 添加计算属性 ```swift extension Double { var km: Double { self * 1000 } var cm: Double { self / 100 } } print(5.0.km) // 5000.0 print(120.0.cm) // 1.2 ``` ## 3. 初始化器扩展 扩展也能添加新的初始化方法。 ```swift struct Point { var x = 0.0, y = 0.0 } extension Point { init(value: Double) { self.x = value self.y = value } } let p = Point(value: 3.0) print(p) // Point(x: 3.0, y: 3.0) ``` ## 4. 协议 + 扩展 扩展能给协议提供 **默认实现**。 ```swift protocol Greetable { func greet() } extension Greetable { func greet() { print("你好，欢迎学习 Swift!") } } struct Student: Greetable {} let s = Student() s.greet() // 你好，欢迎学习 Swift! ``` ## 5. 限制扩展 可以通过 `where` 限制扩展只对特定类型生效。 ```swift extension Collection where Element: Comparable { func isSorted() -> Bool { return self == self.sorted() } } print([1, 2, 3].isSorted()) // true print([3, 1, 2].isSorted()) // false ``` ## 总结 - **扩展** 可以给已有类型添加 **方法、属性、初始化器**。 - **协议扩展** 能写默认实现，非常常用。 - 可以用 **`where` 限制扩展范围**。 - 扩展不会覆盖原有实现，但能让代码更简洁。 ]]> http://herong.info/posts/swift-quickstart/14-错误处理 http://herong.info/posts/swift-quickstart/14-错误处理 Sun, 14 Sep 2025 00:00:00 GMT 在 Swift 中，错误处理主要通过 **`throw` / `try` / `catch`** 来实现。 > 和异常不同，Swift 错误必须显式声明和处理，更安全。 ## 1. 定义错误类型 Swift 的错误必须遵循 `Error` 协议。 ```swift enum FileError: Error { case notFound case noPermission } ``` ## 2. 抛出错误 ```swift func readFile(name: String) throws -> String { if name == "secret.txt" { throw FileError.noPermission } return "文件内容" } ``` ## 3. 捕获错误 ```swift do { let content = try readFile(name: "secret.txt") print(content) } catch FileError.notFound { print("❌ 文件未找到") } catch FileError.noPermission { print("⛔ 没有权限") } catch { print("⚠️ 其它错误：\(error)") } ``` ## 4. try? 和 try! - **`try?`**：错误时返回 `nil`。 - **`try!`**：确定不会出错时使用，出错会崩溃。 ```swift let result1 = try? readFile(name: "a.txt") // Optional("文件内容") let result2 = try? readFile(name: "secret.txt") // nil let result3 = try! readFile(name: "a.txt") // 强制执行 ``` ## 5. defer（清理资源） `defer` 块中的代码在函数结束时执行，常用于释放资源。 ```swift func processFile() throws { print("开始处理文件") defer { print("关闭文件") } throw FileError.notFound } try? processFile() // 输出： // 开始处理文件 // 关闭文件 ``` ### defer 的实战应用：回调清理 ```swift // 系统 API 回调中的资源清理 public func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) { defer { self.callback = nil // 确保函数退出前清理回调 } self.callback?(self.toJSON(["ok": false, "errMsg": error.localizedDescription])) } ``` #### defer 的执行时机 ```swift func demonstrateDefer() { print("1. 函数开始") defer { print("4. defer 块执行") } print("2. 中间逻辑") if someCondition { print("3a. 提前返回") return // defer 仍会执行 } print("3b. 正常结束") // defer 在这里执行 } // 输出（提前返回情况）： // 1. 函数开始 // 2. 中间逻辑 // 3a. 提前返回 // 4. defer 块执行 ``` #### 多个 defer 的执行顺序 ```swift func multipleDefer() { defer { print("第一个 defer") } defer { print("第二个 defer") } defer { print("第三个 defer") } print("函数主体") } multipleDefer() // 输出（后进先出 LIFO）： // 函数主体 // 第三个 defer // 第二个 defer // 第一个 defer ``` #### defer 的实际应用场景 ```swift // 1. 文件操作清理 func readFileWithCleanup(_ path: String) -> String? { let file = openFile(path) defer { closeFile(file) // 确保文件被关闭 } guard file.isValid else { return nil } return file.readContent() } // 2. 网络请求状态管理 func performNetworkRequest() { isLoading = true defer { isLoading = false // 确保加载状态被重置 } // 网络请求逻辑 if requestFailed { return // defer 仍会执行，isLoading 会被设为 false } processResponse() } // 3. 数据库事务管理 func updateDatabase() throws { let transaction = database.beginTransaction() defer { if transaction.isActive { transaction.rollback() // 确保事务被回滚或提交 } } try database.insert(record1) try database.insert(record2) transaction.commit() } // 4. 认证回调清理（你的代码） class AuthManager { private var callback: ((String) -> Void)? func authenticate(_ options: String, _ cb: @escaping (String) -> Void) { self.callback = cb // 执行认证... } // 成功回调 func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) { defer { self.callback = nil // 确保回调被清理 } // 处理成功结果 let result = processAuthorization(authorization) self.callback?(result) } // 失败回调（你的代码） public func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) { defer { self.callback = nil // 无论如何都清理回调 } self.callback?(self.toJSON(["ok": false, "errMsg": error.localizedDescription])) } } ``` #### defer vs 普通清理的对比 ```swift // ❌ 容易遗漏清理的写法 func badCleanupExample() { self.callback = someCallback if condition1 { self.callback = nil // 需要手动清理 return } if condition2 { // 忘记清理 callback！ return } doSomething() self.callback = nil // 需要手动清理 } // ✅ 使用 defer 确保清理 func goodCleanupExample() { defer { self.callback = nil // 自动清理，不会遗漏 } self.callback = someCallback if condition1 { return // defer 自动执行 } if condition2 { return // defer 自动执行 } doSomething() // defer 自动执行 } ``` ## 总结 - 用 `enum` + `Error` 定义错误类型。 - 用 `throw` 抛出，用 `try` + `catch` 捕获。 - `try?` 返回可选，`try!` 强制执行。 - `defer` 用于清理收尾。 ]]> http://herong.info/posts/swift-quickstart/15-泛型 http://herong.info/posts/swift-quickstart/15-泛型 Sun, 14 Sep 2025 00:00:00 GMT 泛型（Generics）让你编写 **可复用、灵活、安全** 的代码。 > 通过占位符 `T` 表示任意类型，避免重复写同样的函数或类。 ## 1. 泛型函数 ```swift func swapTwoValues(_ a: inout T, _ b: inout T) { let temp = a a = b b = temp } var x = 5, y = 10 swapTwoValues(&x, &y) print(x, y) // 10 5 var s1 = "hello", s2 = "world" swapTwoValues(&s1, &s2) print(s1, s2) // world hello ``` ## 2. 泛型类型（结构体 / 类） ```swift struct Stack { private var items: [T] = [] mutating func push(_ item: T) { items.append(item) } mutating func pop() -> T? { return items.popLast() } } var intStack = Stack() intStack.push(1) intStack.push(2) print(intStack.pop()!) // 2 ``` ## 3. 类型约束 有时需要限定泛型类型必须遵循某个协议。 ```swift func findIndex(of value: T, in array: [T]) -> Int? { for (index, item) in array.enumerated() { if item == value { return index } } return nil } print(findIndex(of: "b", in: ["a", "b", "c"])) // 1 ``` ## 4. 关联类型（协议里的泛型） ```swift protocol Container { associatedtype Item mutating func add(_ item: Item) var count: Int { get } } struct IntContainer: Container { var items: [Int] = [] mutating func add(_ item: Int) { items.append(item) } var count: Int { items.count } } ``` ## 总结 - 泛型函数：`func foo(...) {}` - 泛型类型：`struct Stack {...}` - 类型约束：`` - 协议可用 `associatedtype` 声明泛型。 ]]> http://herong.info/posts/swift-quickstart/16-访问控制 http://herong.info/posts/swift-quickstart/16-访问控制 Sun, 14 Sep 2025 00:00:00 GMT Swift 提供访问控制（Access Control）来保护代码的内部实现。 > 通过 `open`、`public`、`internal`、`fileprivate`、`private` 关键字控制作用范围。 ## 1. 五种访问级别 1. **open** - 最宽松，允许模块外使用，并且可以继承 / 重写。 - 主要用于 **框架对外 API**。 2. **public** - 模块外可以使用，但不能继承或重写。 - 适合对外只读的接口。 3. **internal**（默认） - 只能在 **同一模块** 内使用。 - 一般项目中大部分代码都是 `internal`。 4. **fileprivate** - 限制在 **同一个文件** 内访问。 5. **private** - 最严格，限制在 **同一个作用域**（类 / 结构体）内使用。 ## 2. 使用示例 ```swift open class OpenClass { open func openMethod() {} public func publicMethod() {} internal func internalMethod() {} fileprivate func filePrivateMethod() {} private func privateMethod() {} } let obj = OpenClass() obj.publicMethod() // ✅ 可访问 obj.internalMethod() // ✅ 同模块可访问 // obj.filePrivateMethod() ❌ 其他文件不可访问 // obj.privateMethod() ❌ 作用域外不可访问 ``` ## 3. 常见使用场景 - **open**：SDK / Framework 提供可继承的基类。 - **public**：模块对外公开的常量或函数。 - **internal**：默认级别，适合大部分业务代码。 - **fileprivate**：隐藏某些工具函数。 - **private**：保护类内部细节。 ## 4. 注意事项 - 属性、方法、初始化器、扩展都可以设置访问级别。 - 子类的访问级别不能高于父类。 - 协议的访问级别会影响其实现。 ## 总结 - Swift 默认访问级别是 `internal`。 - 最常用的是 `internal` + `private`，只在需要开放 API 时用 `public` 或 `open`。 ]]> http://herong.info/posts/swift-quickstart/17-继承与多态 http://herong.info/posts/swift-quickstart/17-继承与多态 Sun, 14 Sep 2025 00:00:00 GMT Swift 是面向对象语言，支持 **继承** 与 **多态**，但比起某些语言更强调组合。 ## 1. 基本继承 ```swift class Animal { var name: String init(name: String) { self.name = name } func makeSound() { print("...") } } class Dog: Animal { func fetch() { print("\(name) is fetching!") } // 重写父类方法 override func makeSound() { print("Woof!") } } let dog = Dog(name: "Buddy") dog.makeSound() // Woof! dog.fetch() // Buddy is fetching! ``` ## 2. 多态 父类引用可以指向子类对象： ```swift let a: Animal = Dog(name: "Max") a.makeSound() // 调用的是 Dog 的实现 -> "Woof!" ``` 这就是 **多态**：相同的接口，表现不同的行为。 ## 3. `final` 关键字 如果不希望类被继承，可以用 `final`： ```swift final class Cat: Animal { override func makeSound() { print("Meow!") } } // ❌ 下面代码会报错：不能继承 final 类 // class Kitten: Cat {} ``` ## 4. 构造器的继承与重写 子类如果没有写构造器，会自动继承父类的构造器。 ```swift class Bird: Animal { override func makeSound() { print("Chirp!") } } let b = Bird(name: "Tweety") // ✅ 直接用父类 init ``` 如果写了自己的 `init`，可能需要 `super.init`： ```swift class Parrot: Animal { var color: String init(name: String, color: String) { self.color = color super.init(name: name) // 必须调用父类构造器 } } ``` ## 5. 多态与协议的对比 - **继承**：类与类之间的关系，强调 "is-a"。 - **协议**：行为的抽象，强调 "can-do"。 - 在 Swift 开发中，协议比继承更常用。 ## 总结 - 继承允许子类扩展和重写父类功能。 - 多态通过父类引用调用子类实现。 - 使用 `final` 可以禁止继承。 - Swift 提倡 **少用继承，多用协议与组合**。 ]]> http://herong.info/posts/swift-quickstart/18-协议进阶 http://herong.info/posts/swift-quickstart/18-协议进阶 Sun, 14 Sep 2025 00:00:00 GMT 协议（`protocol`）是 Swift 的核心特性之一。它不仅能定义行为接口，还能与扩展、泛型、面向协议编程结合，形成比继承更强大的抽象。 ## 1. 协议继承 协议可以继承其他协议： ```swift protocol Named { var name: String { get } } protocol Aged { var age: Int { get } } protocol Person: Named, Aged {} struct Student: Person { var name: String var age: Int } ``` ## 2. 协议中的构造器 协议可以要求实现某些构造器： ```swift protocol Initializable { init(value: Int) } class NumberBox: Initializable { var value: Int required init(value: Int) { // required 表示所有子类必须实现 self.value = value } } ``` ## 3. 协议扩展（默认实现） 协议扩展可以提供默认实现，让协议更像“接口 + 实现”： ```swift protocol Drawable { func draw() } extension Drawable { func draw() { print("Default drawing...") } } struct Circle: Drawable {} // 没实现 draw()，会用默认实现 Circle().draw() // Default drawing... ``` 也可以在扩展里添加新的方法： ```swift extension Drawable { func debug() { print("Debugging drawable object") } } Circle().debug() // Debugging drawable object ``` --- ## 4. 协议与泛型 协议常与泛型结合，用 `where` 约束类型： ```swift protocol Summable { static func +(lhs: Self, rhs: Self) -> Self } func add(_ a: T, _ b: T) -> T { return a + b } extension Int: Summable {} extension Double: Summable {} print(add(3, 5)) // 8 print(add(2.5, 7.1)) // 9.6 ``` --- ## 5. 面向协议编程（POP） Swift 鼓励 **Protocol-Oriented Programming**（POP），比继承更灵活： - 协议定义能力（能做什么）。 - 结构体/类采用协议，组合出需要的行为。 - 协议扩展提供默认实现，减少重复代码。 示例： ```swift protocol Flyable { func fly() } extension Flyable { func fly() { print("Flying...") } } struct Bird: Flyable {} struct Airplane: Flyable {} Bird().fly() // Flying... Airplane().fly() // Flying... ``` --- ## 总结 - 协议支持继承、构造器要求。 - 协议扩展提供默认实现，提升代码复用。 - 协议与泛型结合更强大。 - 面向协议编程是 Swift 的核心思想。 ]]> http://herong.info/posts/swift-quickstart/19-内存管理 http://herong.info/posts/swift-quickstart/19-内存管理 Sun, 14 Sep 2025 00:00:00 GMT Swift 使用 **ARC（Automatic Reference Counting）** 自动管理内存，大多数情况下不需要手动释放对象。但理解其工作原理非常重要，尤其是避免循环引用。 ## 1. ARC 的基本原理 - 每个类实例都有一个 **引用计数**。 - 当引用 +1 时，实例保留。 - 当引用变为 0 时，实例被销毁。 ```swift class Person { let name: String init(name: String) { self.name = name } deinit { print("\(name) 被销毁") } } var p1: Person? = Person(name: "Tom") p1 = nil // 引用计数归零，触发 deinit ``` ## 2. 强引用（Strong Reference） 默认情况下，变量保存对象时会创建一个 **强引用**。 ```swift class Dog {} var d1: Dog? = Dog() var d2 = d1 // d1, d2 都是强引用 ``` ## 3. 循环引用问题 如果两个对象相互持有强引用，会导致 **循环引用**，对象无法释放。 ```swift class Teacher { var student: Student? deinit { print("Teacher deinit") } } class Student { var teacher: Teacher? deinit { print("Student deinit") } } var t: Teacher? = Teacher() var s: Student? = Student() t?.student = s s?.teacher = t t = nil s = nil // ❌ Teacher 和 Student 都不会释放 ``` ## 4. 解决循环引用 ### 4.1 弱引用（weak） - 用 `weak` 修饰，引用不会增加计数。 - 常用于 **可选类型**，引用对象销毁后会自动设为 `nil`。 ```swift class Teacher { var student: Student? deinit { print("Teacher deinit") } } class Student { weak var teacher: Teacher? // 🔑 解决循环引用 deinit { print("Student deinit") } } ``` ### 4.2 无主引用（unowned） - 用 `unowned` 修饰，不会增加计数。 - **不会自动置 nil**，适合生命周期一致的对象。 ```swift class CreditCard { unowned let customer: Customer // 永远存在 init(customer: Customer) { self.customer = customer } deinit { print("Card deinit") } } class Customer { var card: CreditCard? deinit { print("Customer deinit") } } var c: Customer? = Customer() c?.card = CreditCard(customer: c!) c = nil // 两个对象都释放 ``` ## 5. 闭包捕获列表 闭包也可能导致循环引用，需要用 `[weak self]` 或 `[unowned self]`。 ```swift class ViewController { var name = "VC" var callback: (() -> Void)? func setup() { callback = { [weak self] in print(self?.name ?? "nil") } } deinit { print("VC deinit") } } ``` ## 总结 - Swift 使用 ARC 自动管理内存。 - 循环引用是主要问题，需要 `weak` 或 `unowned` 解决。 - 闭包中捕获 `self` 时，注意使用捕获列表。 ]]> http://herong.info/posts/swift-quickstart/20-并发与异步 http://herong.info/posts/swift-quickstart/20-并发与异步 Sun, 14 Sep 2025 00:00:00 GMT Swift 从 5.5 开始引入了现代化的 **并发模型**，主要包括 `async/await`、`Task`、以及 `Actor`。它让异步代码更直观，也避免了回调地狱。 ## 1. async/await 基础 用 `async` 标记异步函数，用 `await` 调用它。 ```swift func fetchData() async -> String { return "数据结果" } Task { let result = await fetchData() print(result) } ``` ## 2. 异步任务 Task `Task {}` 可以在任何地方开启一个并发任务。 ```swift Task { print("开始下载") let data = await fetchData() print("下载完成: \(data)") } ``` ## 3. 并发执行 多个异步任务可以 **并发执行**。 ```swift func task1() async -> String { try? await Task.sleep(nanoseconds: 1_000_000_000) return "任务1完成" } func task2() async -> String { return "任务2完成" } Task { async let r1 = task1() async let r2 = task2() print(await r1, await r2) } ``` ## 4. 异步序列 异步版本的 `for-in`，用于流式数据。 ```swift func numbers() -> AsyncStream { AsyncStream { continuation in for i in 1...3 { continuation.yield(i) } continuation.finish() } } Task { for await num in numbers() { print(num) } } ``` ## 5. Actor（解决共享数据并发问题） `Actor` 用来保证数据的 **线程安全**。 ```swift actor Counter { var value = 0 func increment() { value += 1 } } let counter = Counter() Task { await counter.increment() print(await counter.value) } ``` ## 6. 与传统回调互操作 老的 **回调 API** 可以通过 `withCheckedContinuation` 转成 `async`。 ```swift func loadData(completion: @escaping (String) -> Void) { DispatchQueue.global().async { completion("旧API数据") } } func loadDataAsync() async -> String { await withCheckedContinuation { cont in loadData { result in cont.resume(returning: result) } } } Task { print(await loadDataAsync()) } ``` --- ## 总结 - `async/await` 让异步代码像同步一样易读。 - `Task` 开启并发任务，`async let` 并发执行多个任务。 - `Actor` 提供线程安全的数据访问。 - 旧回调 API 可以用 `Continuation` 封装成异步。 ]]> http://herong.info/posts/swift-quickstart/21-Swift 模块化编程速成：以 PasskeysNative 为例 http://herong.info/posts/swift-quickstart/21-Swift 模块化编程速成：以 PasskeysNative 为例 Wed, 17 Sep 2025 00:00:00 GMT Void) // ... @objc public func authenticate(_ optionsJson: String, _ cb: @escaping (String) -> Void) // ... ASAuthorizationControllerDelegate 回调 } ``` > 目标：把它抽为 **独立模块**，对外只暴露 `register(optionsJson, cb)` 与 `authenticate(optionsJson, cb)`，内部细节（Base64 工具、iOS 16+ 适配、系统回调）全部**隐藏**。 # 第一部分 · 最常用最重要（先用起来） ## 1. 划定模块边界与对外 API **原则**： - 仅把**稳定能力**标注为 `public` / `@objc` 暴露给上层（UTS/JS 桥）。 - 细节工具与策略（Base64url、JSON 解析、错误组装）一律 `internal`/`private`。 - **输入**：`optionsJson`（WebAuthn 标准字段，经由前端/服务器下发）。 - **输出**：统一的回调 JSON：`{"ok": true, "data": {...}} | {"ok": false, "errMsg": "..."}`。 **建议 API（示意）**： ```swift @objc public protocol PasskeysAPI { // 复杂：跨语言回调形态与线程切换 // ↑ 在复杂逻辑上一行加注释 func register(_ optionsJson: String, _ cb: @escaping (String) -> Void) func authenticate(_ optionsJson: String, _ cb: @escaping (String) -> Void) } ``` > 说明：把协议放在模块 `Public` 目录，类 `PasskeysNative` 作为默认实现，后续可无痛替换（比如接入外部安全 Key 的实现）。 ## 2. 产物类型：Swift Package vs XCFramework（怎么交付） **Swift Package（首选）** - 优点：源码分发、版本化清晰、集成简单（Xcode/SwiftPM 原生支持）。 - 适合团队内部与持续演进。 **XCFramework（二进制）** - 优点：隐藏源码、冷启动更快、适合跨项目/商业分发。 - 用法：`xcodebuild -create-xcframework -framework ... -output Passkeys.xcframework`。 > 推荐：**先 SwiftPM，后期有保密/性能诉求再补二进制 XCFramework**。 ## 3. 输入输出契约（最易踩坑的地方） - **输入**：`PublicKeyCredentialCreationOptions` / `RequestOptions` 的**对象本体**（不是 `{ publicKey: {} }` 外包一层）。 - **字段**：`rp.id`、`challenge`、`user.id`/`user.name`、`rpId` 等必须存在。 - **编码**：二进制字段（`challenge`、`user.id`、`rawId`等）统一 **Base64URL**。 - **输出**：遵循 WebAuthn 前端预期形态（`id/rawId/type/response/...`）。 - **错误**：固定 `ok/errMsg` 键，便于前端/UTS 无分支解析。 > 小贴士：JSON 序列化失败、必填字段缺失、平台版本不符，**都走同一错误模型**，前端体验最稳定。 ## 4. 平台/版本兼容策略（iOS 16+） - `ASAuthorizationPlatformPublicKeyCredential*` 需要 **iOS 16+**。 - 在 API 内部用 `#available(iOS 16.0, *)` **短路返回**统一错误（`"iOS 16+ required"`）。 - 不把平台细节泄露到 API 边界之外（对外只看 `ok/errMsg`）。 ## 第二部分 · 深入与难点（架构/工程化） ### A. 面向协议的抽象与依赖倒置 - **问题**：未来可能接入 FIDO 外置 Key、模拟器桩件或切换到不同系统 API。 - **做法**：抽象协议并**依赖接口**而非具体类。 ```swift // 复杂：抽象系统提供者，便于注入 mock 与多实现 // ↑ 在复杂逻辑上一行加注释 protocol CredentialProvider { func makeRegistrationRequest(rpId: String, challenge: Data, userName: String, userId: Data) -> ASAuthorizationRequest func makeAssertionRequest(rpId: String, challenge: Data) -> ASAuthorizationRequest } ``` > `PasskeysNative` 通过构造函数接收 `CredentialProvider`，测试时注入 **FakeProvider**。 ### B. 并发模型：从回调到 async/await（可选） - 门面层保留回调（兼容跨语言），**内部**可封装为 `async`： - 回调转 `CheckedContinuation`。 - 上层 Swift 调用者可获得 `let result = try await client.register(options:)` 的良好体验。 - 对外仍只暴露回调方法，保持跨语言稳定。 ### C. 错误域与分类 - 自定义 `PasskeysError: Error`，内部归类： - `.invalidOptions(field: String)`、`.platformUnsupported(min: "iOS16")`、`.system(Error)`、`.encoding`。 - **统一映射**到 `errMsg` 字符串，**不上抛内部类型**到跨语言边界。 ### D. 跨语言边界与可见性 - 需要 `@objc` + `NSObject` + `public` 才能被 UTS/JS 调用。 - 注意 `nullability` 与 Swift/ObjC 桥接（`String?` / `Data?`）。 - `JSONSerialization` 用 `try?` + 可控的默认值**收口错误**。 ## E. 测试策略 - **单测**： - Base64URL 编解码（空输入、无填充、多填充）。 - JSON 契约（必填字段缺失 → 错误）。 - iOS16 可用性分支。 - **组件测试**： - 用 Fake `CredentialProvider` 模拟成功/失败/取消回调。 - **UI/集成**： - 最小 Demo App 调通真实设备的注册/登录流程。 ## F. 工程化：版本与分发 - **语义化版本**：`MAJOR.MINOR.PATCH`。 - 修改 JSON 字段 →**MAJOR**。 - 新增字段（向后兼容）→**MINOR**。 - 修复/优化 →**PATCH**。 - **二进制分发**（可选）：出 `*.xcframework` + 校验脚本（`codesign --verify`）。 ## G. 文档化与可发现性 - 用 **DocC** 为 `PasskeysAPI` 生成文档； - 在包内提供 `Examples/`，含最小调用样例与 JSON 模版。 --- # 目录结构建议（可直接照搬） ``` PasskeysKit/ ├─ Package.swift ├─ Sources/ │ └─ PasskeysKit/ │ ├─ Public/ │ │ ├─ PasskeysAPI.swift │ │ └─ PasskeysErrors.swift │ └─ Internal/ │ ├─ PasskeysNative.swift │ ├─ CredentialProvider.swift │ ├─ Base64URL.swift │ └─ JSONCoder.swift └─ Tests/ └─ PasskeysKitTests/ ├─ Base64URLTests.swift ├─ OptionsParsingTests.swift └─ PlatformAvailabilityTests.swift ``` --- # 模块化落地清单（Checklist） - [ ] Public API **最小化**，仅暴露 `register/authenticate`。 - [ ] 输入/输出 JSON 契约文档齐全，错误模型统一。 - [ ] `#available(iOS 16, *)` 在内部**短路**，不外泄平台细节。 - [ ] SwiftPM 集成通过；必要时补 XCFramework。 - [ ] 协议抽象 + 依赖注入，测试可控。 - [ ] 版本语义化与变更日志。 - [ ] DocC 文档与 `Examples/` 示例齐备。 --- # 常见坑位与规避 - **Base64URL** 填充处理：注意 `=` 去/补；空字符串与非法字符要兜底为空 `Data()`。 - **回调置空**：一次请求结束后 `callback = nil`，避免多次触发或悬挂引用。 - **线程语义**：系统回调不保证在主线程；UI 更新前**切主线程**。 - **`presentationAnchor`**：确保返回 **keyWindow**；多场景时注意窗口切换。 - **版本分支**：把 `iOS 16+` 检查放在**最前**，尽早失败、错误可预期。 - **跨语言兼容**：`@objc public` 与 `NSObject` 继承别漏；字符串编码用 UTF-8。 --- # 结语 把功能做成**小而稳的模块**，先对外统一契约，再在内部迭代实现，是 Swift/iOS 项目长期可维护的关键。你现在的 `PasskeysNative` 已经很接近理想门面：**只需把工具与系统细节收入 Internal，把 API 抽到 Public 协议里**，就能在不破坏上层调用的前提下，持续演进到更专业的工程形态。 ]]> http://herong.info/posts/swift-quickstart/22-模块导入与导出 http://herong.info/posts/swift-quickstart/22-模块导入与导出 Wed, 17 Sep 2025 00:00:00 GMT 如何导入系统框架、第三方库，以及如何设计自己的模块对外接口。 ## 什么是模块（Module） 在 Swift 中，**模块**是代码分发的基本单位。每个模块都有自己的命名空间，可以包含类、结构体、协议、函数等。 常见的模块类型： - **系统框架**：`Foundation`、`UIKit`、`SwiftUI` 等 - **第三方库**：通过 CocoaPods、Swift Package Manager 安装的库 - **自定义模块**：你自己创建的 Swift Package 或 Framework ## import 语法详解 ### 1. 基础导入语法 ```swift // 导入整个模块 import Foundation import UIKit import AuthenticationServices // 导入后就可以使用模块中的公开类型 let date = Date() // Foundation.Date let label = UILabel() // UIKit.UILabel ``` ### 2. 选择性导入 ```swift // 只导入模块中的特定类型 import class UIKit.UIViewController import struct Foundation.URL import enum Foundation.ComparisonResult // 导入特定函数 import func Darwin.sqrt ``` ### 3. 重命名导入 ```swift // 避免命名冲突 import UIKit import class MyFramework.UIView as MyUIView // 使用时区分 let systemView = UIView() // UIKit.UIView let customView = MyUIView() // MyFramework.UIView ``` ### 4. 测试专用导入 ```swift // 仅在测试环境导入 #if DEBUG import TestingFramework #endif @testable import MyApp // 可以访问 internal 级别的内容 ``` ## 你提到的三个框架详解 ### Foundation ```swift import Foundation // Foundation 提供基础数据类型和系统服务 let string = "Hello" let date = Date() let url = URL(string: "https://example.com") let data = Data() let userDefaults = UserDefaults.standard ``` **常用场景**：字符串处理、日期时间、网络请求、数据存储、JSON 解析 ### UIKit ```swift import UIKit // UIKit 提供 iOS 用户界面组件 let viewController = UIViewController() let label = UILabel() let button = UIButton(type: .system) let imageView = UIImageView() ``` **常用场景**：构建传统 iOS 界面、处理触摸事件、导航控制、动画 ### AuthenticationServices ```swift import AuthenticationServices // 提供生物识别、Passkeys 等认证服务 let context = ASAuthorizationController() let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: "example.com") ``` **常用场景**：Face ID/Touch ID 认证、Passkeys 登录、Safari 密码自动填充 ## 模块的访问控制 ### 访问级别从高到低 ```swift // 1. open - 最开放，可被其他模块继承和重写 open class BaseViewController: UIViewController { open func setup() { } } // 2. public - 可被其他模块访问，但不能继承 public class APIClient { public func request() { } } // 3. internal - 模块内部可访问（默认级别） internal class NetworkManager { func sendRequest() { } } // 4. fileprivate - 同一文件内可访问 fileprivate class FileHelper { func process() { } } // 5. private - 最严格，只有当前作用域可访问 private class Secret { private func encrypt() { } } ``` ## 如何设计可导出的模块 ### 1. 创建 Swift Package ```bash # 创建新的 Swift Package mkdir MyAwesomeKit cd MyAwesomeKit swift package init --type library ``` 生成的 `Package.swift`： ```swift // swift-tools-version: 5.9 import PackageDescription let package = Package( name: "MyAwesomeKit", products: [ .library( name: "MyAwesomeKit", targets: ["MyAwesomeKit"]), ], targets: [ .target( name: "MyAwesomeKit", dependencies: []), .testTarget( name: "MyAwesomeKitTests", dependencies: ["MyAwesomeKit"]), ] ) ``` ### 2. 设计公开 API ```swift // Sources/MyAwesomeKit/MyAwesomeKit.swift import Foundation // 对外暴露的主要接口 public class NetworkClient { public init() {} public func get(url: String) async throws -> Data { // 实现网络请求 return Data() } } // 对外暴露的协议 public protocol DataProcessor { func process(_ data: Data) -> String } // 内部实现，不对外暴露 internal class InternalHelper { static func format(_ data: Data) -> String { return String(data: data, encoding: .utf8) ?? "" } } // 私有实现 private extension NetworkClient { func buildRequest(url: String) -> URLRequest? { guard let url = URL(string: url) else { return nil } return URLRequest(url: url) } } ``` ### 3. 使用你的模块 ```swift // 在其他项目中使用 import MyAwesomeKit class ViewController: UIViewController { let client = NetworkClient() override func viewDidLoad() { super.viewDidLoad() Task { do { let data = try await client.get(url: "https://api.example.com") print("获取到数据：\(data.count) bytes") } catch { print("请求失败：\(error)") } } } } ``` ## 实际开发中的最佳实践 ### 1. 按功能模块化导入 ```swift // 好的做法：按需导入 import Foundation // 基础类型 import UIKit // UI 组件 import AuthenticationServices // 认证相关 class LoginViewController: UIViewController { // 使用各个模块的功能 } ``` ### 2. 避免循环依赖 ```swift // ❌ 避免这样的循环依赖 // ModuleA 导入 ModuleB // ModuleB 导入 ModuleA // ✅ 正确做法：提取公共协议到独立模块 // ModuleA 和 ModuleB 都依赖 CommonProtocols ``` ### 3. 合理设计访问级别 ```swift public class UserManager { // 对外接口 public func login(username: String, password: String) async -> Bool { return await performLogin(username, password) } // 内部实现 private func performLogin(_ username: String, _ password: String) async -> Bool { // 具体登录逻辑 return true } // 内部状态 private var isLoggedIn = false } ``` ## 常见问题与解决方案 ### 问题 1：模块找不到 ```swift // 错误信息：No such module 'SomeFramework' // 解决方案： // 1. 检查 import 语句拼写 // 2. 确认已在 Package.swift 或 Podfile 中添加依赖 // 3. 清理构建缓存：Product → Clean Build Folder ``` ### 问题 2：访问级别错误 ```swift // 错误信息：'SomeClass' is inaccessible due to 'internal' protection level // 解决方案：确保要访问的类型标记为 public 或 open // 模块内部 public class SomeClass { // 添加 public 关键字 public init() {} // 构造函数也需要 public } ``` ### 问题 3：命名冲突 ```swift // 两个模块都有同名类型 import ModuleA import ModuleB // 使用完整名称区分 let a = ModuleA.SomeClass() let b = ModuleB.SomeClass() // 或者使用重命名导入 import struct ModuleB.SomeClass as ModuleBClass ``` ## 小结 这一篇我们学习了 Swift 的模块系统： - **import 语法**：基础导入、选择性导入、重命名导入 - **系统框架**：Foundation、UIKit、AuthenticationServices 的用途 - **访问控制**：open、public、internal、fileprivate、private 五个级别 - **模块设计**：如何创建可复用的 Swift Package - **最佳实践**：避免循环依赖、合理设计 API、处理常见问题 下一篇我们将学习 Swift 的包管理器和依赖管理，让你能够更好地使用和分发 Swift 模块。 ]]> http://herong.info/posts/swift-quickstart/23-系统API调用与数据流 http://herong.info/posts/swift-quickstart/23-系统API调用与数据流 Wed, 17 Sep 2025 00:00:00 GMT 本文专门讲解如何调用 iOS 系统 API，以 AuthenticationServices 框架的 Passkeys 实现为例，展示完整的数据流转和方法调用过程。 ## 系统 API 调用的基本模式 ### 典型的调用流程 ```swift // 1. 创建提供者（Provider） let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: rpId) // 2. 创建请求（Request） let request = provider.createCredentialRegistrationRequest( challenge: fromB64url(challengeB64), name: userName, userID: fromB64url(userIdB64) ) // 3. 创建控制器（Controller） let controller = ASAuthorizationController(authorizationRequests: [request]) // 4. 配置控制器 controller.delegate = self controller.presentationContextProvider = self // 5. 存储回调 self.callback = cb // 6. 执行请求 controller.performRequests() ``` ## 逐步分解：类与方法详解 ### 1. ASAuthorizationPlatformPublicKeyCredentialProvider ```swift let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: rpId) ``` **类的作用**： - 这是 Apple 提供的 **Passkeys 凭证提供者** - 负责与系统的 Passkeys 存储进行交互 - `relyingPartyIdentifier` 是网站/应用的唯一标识符（如 "example.com"） **初始化参数**： ```swift // rpId 通常是域名，用于标识这个 Passkey 属于哪个网站 let rpId = "example.com" let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: rpId) // 实际数据示例 let rpId = "webauthn.example.com" // 从服务器传来的 rp.id 字段 ``` ### 2. createCredentialRegistrationRequest 方法 ```swift let request = provider.createCredentialRegistrationRequest( challenge: fromB64url(challengeB64), // Data 类型 name: userName, // String 类型 userID: fromB64url(userIdB64) // Data 类型 ) ``` **方法作用**： - 创建一个 **注册请求**，用于生成新的 Passkey - 将后端服务器提供的参数转换为系统可识别的格式 **参数详解**： | 参数 | 类型 | 作用 | 数据转换 | | ----------- | -------- | ------------------------ | ---------------- | | `challenge` | `Data` | 防重放攻击的随机挑战码 | Base64URL → Data | | `name` | `String` | 用户标识符（通常是邮箱） | 直接使用 | | `userID` | `Data` | 用户的唯一 ID | Base64URL → Data | #### 数据转换过程详解 ```swift // 服务器发送的原始数据（JSON） let serverData = """ { "rp": {"id": "example.com"}, "user": { "id": "dXNlcjEyMw==", // Base64URL 编码的用户 ID "name": "alice@example.com", // 用户邮箱 "displayName": "Alice Smith" }, "challenge": "Y2hhbGxlbmdl" // Base64URL 编码的挑战码 } """ // 数据转换函数 func fromB64url(_ base64url: String) -> Data { // Base64URL → 标准 Base64 → Data var base64 = base64url .replacingOccurrences(of: "-", with: "+") .replacingOccurrences(of: "_", with: "/") // 添加填充 let padding = (4 - base64.count % 4) % 4 if padding > 0 { base64.append(String(repeating: "=", count: padding)) } return Data(base64Encoded: base64) ?? Data() } // 实际转换过程 let challengeB64 = "Y2hhbGxlbmdl" // 来自服务器 let challengeData = fromB64url(challengeB64) // 转换为 Data // challengeData = <63686161 6c6c656e 6765> // "challenge" 的字节表示 let userIdB64 = "dXNlcjEyMw==" // 来自服务器 let userIdData = fromB64url(userIdB64) // 转换为 Data // userIdData = <75736572 313233> // "user123" 的字节表示 ``` ### 3. ASAuthorizationController ```swift let controller = ASAuthorizationController(authorizationRequests: [request]) ``` **类的作用**： - 这是 Apple 的 **授权控制器** - 负责协调整个认证流程 - 管理用户界面的显示和用户交互 **初始化参数**： ```swift // authorizationRequests 是一个数组，可以包含多个请求 let requests: [ASAuthorizationRequest] = [request] let controller = ASAuthorizationController(authorizationRequests: requests) // 也可以同时支持多种认证方式 let passkeyRequest = provider.createCredentialRegistrationRequest(...) let passwordRequest = ASPasswordCredentialIdentity.init(...) let allRequests = [passkeyRequest, passwordRequest] let controller = ASAuthorizationController(authorizationRequests: allRequests) ``` ### 4. 控制器配置 ```swift controller.delegate = self // 处理认证结果 controller.presentationContextProvider = self // 提供显示窗口 self.callback = cb // 存储回调函数 ``` #### delegate 的作用 ```swift // 当前类需要实现 ASAuthorizationControllerDelegate 协议 extension PasskeysManager: ASAuthorizationControllerDelegate { // 认证成功时调用 - 完整实现 public func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) { defer { self.callback = nil // 确保回调被清理 } if #available(iOS 16.0, *) { // 注册结果 → WebAuthn Create 格式 if let reg = authorization.credential as? ASAuthorizationPlatformPublicKeyCredentialRegistration { let id = b64url(reg.credentialID) let data: [String: Any] = [ "id": id, "rawId": id, "type": "public-key", "response": [ "attestationObject": b64url(reg.rawAttestationObject), "clientDataJSON": b64url(reg.rawClientDataJSON) ], "transports": ["internal"] ] self.callback?(self.toJSON(["ok": true, "data": data])) return } // 登录结果 → WebAuthn Get 格式 if let asr = authorization.credential as? ASAuthorizationPlatformPublicKeyCredentialAssertion { let id = b64url(asr.credentialID) let data: [String: Any] = [ "id": id, "rawId": id, "type": "public-key", "response": [ "authenticatorData": b64url(asr.rawAuthenticatorData), "clientDataJSON": b64url(asr.rawClientDataJSON), "signature": b64url(asr.signature), "userHandle": b64url(asr.userID) ] ] self.callback?(self.toJSON(["ok": true, "data": data])) return } // 未知的凭证类型 self.callback?(self.toJSON(["ok": false, "errMsg": "unsupported credential type"])) } else { // iOS 版本不支持 self.callback?(self.toJSON(["ok": false, "errMsg": "iOS 16+ required"])) } } // 认证失败时调用 func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) { let result = ["ok": false, "errMsg": error.localizedDescription] callback?(toJSON(result)) callback = nil } } ``` #### 成功回调的详细分析 **1. 双重类型检查模式** ```swift // 第一层：版本检查 if #available(iOS 16.0, *) { // 第二层：凭证类型检查 if let reg = authorization.credential as? ASAuthorizationPlatformPublicKeyCredentialRegistration { // 处理注册结果 } else if let asr = authorization.credential as? ASAuthorizationPlatformPublicKeyCredentialAssertion { // 处理登录结果 } else { // 未知类型 } } else { // 版本不支持 } ``` **2. 数据转换流程** ```swift // iOS 系统对象 → WebAuthn 标准格式 // 注册场景的数据转换 let reg = authorization.credential as? ASAuthorizationPlatformPublicKeyCredentialRegistration // 系统数据 reg.credentialID // Data 类型 reg.rawAttestationObject // Data? 类型 reg.rawClientDataJSON // Data 类型 // 转换为前端期望格式 let data = [ "id": b64url(reg.credentialID), // Data → Base64URL "rawId": b64url(reg.credentialID), // Data → Base64URL "type": "public-key", // 固定值 "response": [ "attestationObject": b64url(reg.rawAttestationObject), // Data? → Base64URL "clientDataJSON": b64url(reg.rawClientDataJSON) // Data → Base64URL ], "transports": ["internal"] // 固定值，表示平台内置 ] ``` **3. 两种认证场景的区别** | 场景 | 系统类型 | 关键数据 | 用途 | | -------- | -------------------------------------------------------- | -------------------------------- | ---------------- | | **注册** | `ASAuthorizationPlatformPublicKeyCredentialRegistration` | `attestationObject` | 创建新的 Passkey | | **登录** | `ASAuthorizationPlatformPublicKeyCredentialAssertion` | `signature`, `authenticatorData` | 验证已有 Passkey | ```swift // 注册场景 - 创建新凭证 if let reg = authorization.credential as? ASAuthorizationPlatformPublicKeyCredentialRegistration { // 包含证明对象，用于服务器验证设备的合法性 "attestationObject": b64url(reg.rawAttestationObject) } // 登录场景 - 验证已有凭证 if let asr = authorization.credential as? ASAuthorizationPlatformPublicKeyCredentialAssertion { // 包含签名数据，用于服务器验证用户身份 "signature": b64url(asr.signature), "authenticatorData": b64url(asr.rawAuthenticatorData), "userHandle": b64url(asr.userID) } ``` **4. b64url 函数的作用** ```swift // 将 iOS 系统的 Data 对象转换为 WebAuthn 标准的 Base64URL 格式 func b64url(_ data: Data?) -> String { guard let data = data else { return "" } return data.base64EncodedString() .replacingOccurrences(of: "+", with: "-") .replacingOccurrences(of: "/", with: "_") .replacingOccurrences(of: "=", with: "") } // 使用示例 let credentialId = reg.credentialID // Data let base64urlId = b64url(credentialId) // Base64URL String // "dXNlcjEyMw" （URL 安全的编码格式） ``` **5. 错误处理的层次** ```swift // 层次1：版本兼容性错误 if #available(iOS 16.0, *) { // 支持的版本 } else { callback?(toJSON(["ok": false, "errMsg": "iOS 16+ required"])) } // 层次2：凭证类型错误 if let reg = authorization.credential as? ASAuthorizationPlatformPublicKeyCredentialRegistration { // 已知类型 } else { callback?(toJSON(["ok": false, "errMsg": "unsupported credential type"])) } // 层次3：系统级错误（在 didCompleteWithError 中处理） func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) { callback?(toJSON(["ok": false, "errMsg": error.localizedDescription])) } ``` #### presentationContextProvider 的作用 ```swift // 提供显示认证界面的窗口 extension PasskeysManager: ASAuthorizationControllerPresentationContextProviding { func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor { // 返回当前活跃的窗口 return UIApplication.shared.windows.first { $0.isKeyWindow } ?? UIWindow() } } ``` ### 5. performRequests() 执行 ```swift controller.performRequests() ``` **方法作用**： - 启动整个认证流程 - 这是一个 **异步方法**，会立即返回 - 实际的认证结果通过 delegate 方法返回 ## 完整的数据流转过程 ### 输入数据（来自前端/服务器） ```swift // 1. 前端发送 JSON 字符串 let optionsJson = """ { "rp": { "id": "example.com", "name": "Example Corp" }, "user": { "id": "dXNlcjEyMw==", "name": "alice@example.com", "displayName": "Alice Smith" }, "challenge": "Y2hhbGxlbmdl", "pubKeyCredParams": [ {"type": "public-key", "alg": -7} ] } """ ``` ### 数据解析与转换 ```swift // 2. 解析 JSON guard let data = optionsJson.data(using: .utf8), let options = try? JSONSerialization.jsonObject(with: data) as? [String: Any], let rp = options["rp"] as? [String: Any], let rpId = rp["id"] as? String, let user = options["user"] as? [String: Any], let userIdB64 = user["id"] as? String, let userName = user["name"] as? String, let challengeB64 = options["challenge"] as? String else { return } // 3. Base64URL 解码 let challengeData = fromB64url(challengeB64) // "Y2hhbGxlbmdl" → let userIdData = fromB64url(userIdB64) // "dXNlcjEyMw==" → ``` ### 系统 API 调用 ```swift // 4. 创建系统对象 let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: rpId) let request = provider.createCredentialRegistrationRequest( challenge: challengeData, // Data 类型 name: userName, // "alice@example.com" userID: userIdData // Data 类型 ) // 5. 配置并执行 let controller = ASAuthorizationController(authorizationRequests: [request]) controller.delegate = self controller.presentationContextProvider = self controller.performRequests() // 异步执行 ``` ### 输出数据（返回给前端） ```swift // 6. 在 delegate 方法中处理结果 func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) { if let credential = authorization.credential as? ASAuthorizationPlatformPublicKeyCredentialRegistration { // 提取系统返回的数据 let credentialId = credential.credentialID // Data let attestationObject = credential.rawAttestationObject // Data? let clientDataJSON = credential.rawClientDataJSON // Data // 转换为前端期望的格式 let response = [ "ok": true, "id": credentialId.base64EncodedString(), // Data → Base64 "rawId": credentialId.base64EncodedString(), // Data → Base64 "type": "public-key", "response": [ "attestationObject": attestationObject?.base64EncodedString() ?? "", // Data → Base64 "clientDataJSON": clientDataJSON.base64EncodedString() // Data → Base64 ] ] // 返回 JSON 字符串 callback?(toJSON(response)) } } ``` ## 常见问题与注意事项 ### 1. iOS 版本兼容性 ```swift // Passkeys 需要 iOS 16+ @available(iOS 16.0, *) func createPasskey() { let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: rpId) // ... } // 版本检查 if #available(iOS 16.0, *) { createPasskey() } else { callback?(toJSON(["ok": false, "errMsg": "iOS 16+ required"])) } ``` ### 2. 错误处理 ```swift // 常见错误类型 func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) { let errorMessage: String if let authError = error as? ASAuthorizationError { switch authError.code { case .canceled: errorMessage = "用户取消了认证" case .invalidResponse: errorMessage = "无效的响应" case .notHandled: errorMessage = "认证未处理" case .failed: errorMessage = "认证失败" default: errorMessage = "未知错误: \(error.localizedDescription)" } } else { errorMessage = error.localizedDescription } callback?(toJSON(["ok": false, "errMsg": errorMessage])) } ``` ### 3. 内存管理 ```swift // 避免循环引用 class PasskeysManager { private var callback: ((String) -> Void)? func register(_ options: String, _ cb: @escaping (String) -> Void) { self.callback = cb // ... 执行认证 } // 在 delegate 方法中清理回调 func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) { // 处理结果 callback?(result) callback = nil // 重要：清理引用 } } ``` ## 小结 - **系统 API 调用**遵循：Provider → Request → Controller → Execute 的模式 - **数据转换**是关键：Base64URL ↔ Data ↔ 系统对象 - **异步处理**：通过 delegate 模式处理结果 - **错误处理**：统一的错误模型和版本兼容性检查 - **内存管理**：及时清理回调引用，避免内存泄漏 这种模式在 iOS 开发中极其常见，掌握了这个流程，你就能轻松调用其他系统 API！ ]]> http://herong.info/posts/云开发/生产环境 MySQL 不暴露公网时，本地如何安全连接数据库 http://herong.info/posts/云开发/生产环境 MySQL 不暴露公网时，本地如何安全连接数据库 Fri, 24 Apr 2026 00:00:00 GMT http://herong.info/posts/前端/深入理解 ResizeObserver —— API、回调参数与实战（含 Vue 示例） http://herong.info/posts/前端/深入理解 ResizeObserver —— API、回调参数与实战（含 Vue 示例） Wed, 23 Sep 2026 11:45:26 GMT { for (const entry of entries) { // entry 是 ResizeObserverEntry const el = entry.target as HTMLElement; // contentRect 是旧接口，读内容盒的宽高（不含 padding + border） const { width, height } = entry.contentRect; // 新接口，读“内容盒”尺寸（数组是为多片段布局准备的） const contentInline = entry.contentBoxSize?.[0]?.inlineSize; const contentBlock = entry.contentBoxSize?.[0]?.blockSize; console.log( "元素", el, "内容宽高", width, height, "inline/block", contentInline, contentBlock ); } }); // 开始观察某元素（默认观察 content-box） ro.observe(document.querySelector("#box")!); // 停止观察某元素 // ro.unobserve(document.querySelector('#box')!) // 断开所有观察 // ro.disconnect() ``` --- ## API 详解 ### 构造函数 ```ts const ro = new ResizeObserver(callback); ``` - `callback(entries, observer)`：**尺寸变化**被批处理后调用。**不要**在回调里同步反复修改被观察元素尺寸，否则可能触发 `ResizeObserver loop limit exceeded`。 ### 实例方法 - `observe(target: Element, options?: { box?: 'content-box' | 'border-box' | 'device-pixel-content-box' })` - `unobserve(target: Element)` - `disconnect()` > `box` 含义见后文；不传则等价于 `{ box: 'content-box' }`。 --- ## 回调参数 `entries` 逐项拆解 回调签名： ```ts type ResizeObserverCallback = ( entries: ResizeObserverEntry[], observer: ResizeObserver ) => void; ``` `entries` 是一组 `ResizeObserverEntry`，每个 entry 对应一个发生了尺寸变化的元素。 **ResizeObserverEntry 的属性：** 1. `target: Element` 被观察的元素（你的代码里就是 `div.split-horizontal.w-full`）。 2. `contentRect: DOMRectReadOnly`（**旧接口**，仍被广泛使用） - 表示**内容盒（content-box）**的矩形：`x, y, width, height, top, right, bottom, left` - 不含 `padding` / `border` / `margin`。 - 局限：只能读内容盒；新接口能更灵活区分不同盒模型。 3. `contentBoxSize: ResizeObserverSize[]`（**新接口**） - 表示**内容盒**的尺寸集合（数组是为多片段容器准备的，大多数情况下只有一项）。 - 每一项是 `ResizeObserverSize`： - `inlineSize`: 写入方向的尺寸（在水平书写中等同 width） - `blockSize` : 块方向的尺寸（在水平书写中等同 height） - **优点**：与书写模式（writing-mode）无关，比 `width/height` 更国际化。 4. `borderBoxSize: ResizeObserverSize[]`（**新接口**） - 表示**边框盒**（包括 `padding` + `border`）的尺寸（多数情况仅一项）。 - 当你需要与 CSS `box-sizing: border-box;` 对齐时，应使用它。 5. `devicePixelContentBoxSize: ResizeObserverSize[]`（**新接口**） - 表示**设备像素级**的内容盒尺寸，已经乘上 `devicePixelRatio`。 - 渲染位图（如 ``、高 DPI 图表）时很有用，可减少模糊。 > 兼容性提示：老版 Safari 可能返回 `borderBoxSize` 等为**对象**而非数组，或没有这些属性。要写**兼容代码**（见下文）。 --- ## 观察选项 `box` 如何选择 在 `observe(el, { box })` 里可以指定观测哪种盒子： - `content-box`（默认）：**内容**区域尺寸变化才触发；适合根据内容变化重排。 - `border-box`：包含 `padding + border`；与 `box-sizing: border-box` 设计一致，常用于与布局尺寸对齐。 - `device-pixel-content-box`：内容盒的**设备像素**尺寸（乘上 DPR）；适合 Canvas/图表等需要像素级精度的场景。 **选择建议：** - 你的场景如果是**计算分栏/剩余宽度**，通常选 `border-box` 更直观； - 需要高分屏绘图 → 选 `device-pixel-content-box`； - 默认不指定也能用，但读值时记得从对应的 `*BoxSize` 里拿。 --- ## 常见用法模式（含你的 Split 示例） ### 模式 1：读取“内容盒”宽高（兼容写法） ```ts function getContentSize(entry: ResizeObserverEntry) { // 复杂逻辑：优先用新接口；兼容老浏览器回退到 contentRect const cb = Array.isArray(entry.contentBoxSize) ? entry.contentBoxSize[0] : (entry as any).contentBoxSize; // 某些 Safari 旧版是对象 const width = cb?.inlineSize ?? entry.contentRect.width; const height = cb?.blockSize ?? entry.contentRect.height; return { width, height }; } ``` ### 模式 2：读取“边框盒”宽高（与 border-box 对齐） ```ts function getBorderBoxSize(entry: ResizeObserverEntry) { const bb = Array.isArray(entry.borderBoxSize) ? entry.borderBoxSize[0] : (entry as any).borderBoxSize; // 回退到 contentRect 以避免 undefined const width = bb?.inlineSize ?? entry.contentRect.width; const height = bb?.blockSize ?? entry.contentRect.height; return { width, height }; } ``` ### 模式 3：高 DPI Canvas 自适应 ```ts const ro = new ResizeObserver((entries) => { for (const entry of entries) { const dpcb = Array.isArray(entry.devicePixelContentBoxSize) ? entry.devicePixelContentBoxSize[0] : (entry as any).devicePixelContentBoxSize; const dpr = window.devicePixelRatio || 1; const cssW = entry.contentRect.width; const cssH = entry.contentRect.height; const pixelW = dpcb?.inlineSize ?? Math.round(cssW * dpr); const pixelH = dpcb?.blockSize ?? Math.round(cssH * dpr); // 复杂逻辑：canvas 实际像素用设备像素，样式尺寸保持 CSS 像素一致 canvas.width = pixelW; canvas.height = pixelH; canvas.style.width = cssW + "px"; canvas.style.height = cssH + "px"; } }); ro.observe(canvas, { box: "device-pixel-content-box" }); ``` ### 模式 4：你的 Split-pane 场景 ```ts // 复杂逻辑：观察容器宽度变化，动态设置左右面板尺寸 const horizontalSplitObserver = new ResizeObserver((entries) => { const entry = entries[0]; // 用 border-box 保证与布局占位一致 const { width: containerWidth } = getBorderBoxSize(entry); if (horizontalSplit) { horizontalSplit.setSizes([ sidebarPanelWidth.value, containerWidth - sidebarPanelWidth.value, ]); } }); horizontalSplitObserver.observe( document.querySelector(".split-horizontal.w-full") as Element, { box: "border-box" } ); ``` --- ## 在 Vue 3 中的优雅使用 ```ts ``` --- ## 性能与坑位 1. **批处理调用** 回调不会为每次微小变化都同步触发，浏览器会**合并/节流**。避免在回调内做昂贵计算，可加自节流/防抖。 2. **循环限制错误** 如果回调中**修改了被观察元素的尺寸**，且导致持续触发，会报： > _ResizeObserver loop limit exceeded_ > 解决：在 `requestAnimationFrame`、`setTimeout(0)` 或下一个 tick 再修改 DOM；或把变更施加到**非被观察元素**。 3. **老浏览器兼容** - 旧 Safari 可能将 `*BoxSize` 暴露为**对象**而不是数组；或缺失这些属性（仅有 `contentRect`）。 - 写 **Array/对象双兼容** 与 **`contentRect` 回退** 的读取逻辑。 4. **避免多余观察** 同一个元素不要重复 `observe`；同页面过多观察者需注意内存与回调开销。 5. **与 MutationObserver 区分** - `ResizeObserver` 关注**尺寸**； - `MutationObserver` 关注**DOM 结构/属性**； - `IntersectionObserver` 关注**可见性/交叉状态**。 目标不同，不可互代。 --- ## 调试清单 - ✅ 回调是否触发？（尝试改变容器尺寸，或给目标元素加边框确认） - ✅ `observe` 的元素是否**可渲染且在文档中**？ - ✅ 读取的是哪个盒模型？（`contentRect` vs `borderBoxSize`） - ✅ 是否有循环更改导致 loop exceeded？ - ✅ 是否做了兼容读取（数组/对象/回退到 `contentRect`）？ - ✅ 在组件卸载时 `disconnect()` 了吗？ --- ## 速查表 **构造：** ```ts new ResizeObserver((entries, observer) => { ... }) ``` **Entry 属性：** - `target: Element` - `contentRect: DOMRectReadOnly` ➜ 内容盒矩形（旧） - `contentBoxSize: ResizeObserverSize[]` - `borderBoxSize: ResizeObserverSize[]` - `devicePixelContentBoxSize: ResizeObserverSize[]` **ResizeObserverSize：** - `inlineSize`（水平书写 ≈width） - `blockSize`（水平书写 ≈height） **方法：** ```ts ro.observe(el, { box: "content-box" | "border-box" | "device-pixel-content-box", }); ro.unobserve(el); ro.disconnect(); ``` --- ### 小结 - **entries[0].contentRect**：内容盒 `width/height`（旧、通用）。 - **entries[0].contentBoxSize[0].inlineSize/blockSize**：内容盒 size（新、书写模式友好）。 - **entries[0].borderBoxSize[0]...**：边框盒 size（与 `border-box` 布局一致）。 - **entries[0].devicePixelContentBoxSize[0]...**：设备像素级内容盒（高 DPI 渲染）。 在你的分栏（Split）场景： > 选 `border-box` + 兼容读取 + 异步修改尺寸（必要时 `requestAnimationFrame`），最稳。 ]]> http://herong.info/posts/小程序/小程序里如何做苹果式毛玻璃 Dock http://herong.info/posts/小程序/小程序里如何做苹果式毛玻璃 Dock Sat, 23 May 2026 00:00:00 GMT 换一换 近一点 室内 免费 ``` ### WXSS ```css .glass-dock { position: fixed; left: 24rpx; right: 24rpx; bottom: 160rpx; padding: 12rpx; border-radius: 36rpx; background: rgba(255, 255, 255, 0.56); border: 1px solid rgba(255, 255, 255, 0.68); box-shadow: 0 18rpx 60rpx rgba(16, 24, 40, 0.14); -webkit-backdrop-filter: blur(28rpx) saturate(160%); backdrop-filter: blur(28rpx) saturate(160%); display: flex; gap: 10rpx; } .dock-main-btn, .dock-chip { height: 76rpx; border-radius: 999px; display: flex; align-items: center; justify-content: center; font-weight: 900; } .dock-main-btn { flex: 0 0 220rpx; color: #fff; background: linear-gradient(135deg, #008858, #13c27f); } .dock-chip { flex: 1; color: #1f2933; background: rgba(255, 255, 255, 0.62); border: 1px solid rgba(255, 255, 255, 0.68); } ``` ### 深色模式可选增强 ```css @media (prefers-color-scheme: dark) { .glass-dock { background: rgba(25, 28, 32, 0.5); border-color: rgba(255, 255, 255, 0.14); box-shadow: 0 18rpx 60rpx rgba(0, 0, 0, 0.28); } .dock-chip { background: rgba(255, 255, 255, 0.1); border-color: rgba(255, 255, 255, 0.12); color: #f5f7fa; } } ``` ## 一句话总结 苹果式毛玻璃 = 半透明背景 + 背景模糊 + 饱和度 + 高光边框 + 柔和阴影。 在小程序里，`backdrop-filter` 是锦上添花，半透明背景和阴影才是兼容兜底。 ]]> http://herong.info/posts/工程实践/地点图片派生图实践：原图入库 + COS 裁切 + card-thumb-detail http://herong.info/posts/工程实践/地点图片派生图实践：原图入库 + COS 裁切 + card-thumb-detail Sun, 24 May 2026 10:00:00 GMT B[import-place-media.mjs] B --> C[(lwpm_place_media
variant=original)] C --> D[generate-place-media-variants.mjs] D --> E[COS 原图 URL + imageMogr2] E --> F[fetch 处理后字节流] F --> G[putCosObject 写入 variants/] G --> H[(lwpm_place_media
card/thumb/detail)] H --> I[place.service 公开接口] I --> J[小程序首页/详情] ``` --- ## 数据模型 迁移脚本：`code/database/migrations/manual-20260524-add-place-media-variants.sql` 在 `lwpm_place_media` 上新增两列： | 字段 | 类型 | 含义 | |------|------|------| | `variant` | `ENUM('original','card','thumb','detail')` | 图片用途变体 | | `source_media_id` | `BIGINT NULL` | 派生图指向的原图 `id` | 索引设计： - `idx_place_media_variant (place_id, variant, role, sort_order)`：按地点 + 变体查图 - `uk_place_media_source_variant (source_media_id, variant)`：**同一原图每种变体只保留一条**，脚本可幂等重跑 Entity 映射见 `place-media.entity.ts`： ```typescript export enum MediaVariant { ORIGINAL = 'original', CARD = 'card', THUMB = 'thumb', DETAIL = 'detail', } @Column({ type: 'enum', enum: MediaVariant, default: MediaVariant.ORIGINAL }) variant: MediaVariant = MediaVariant.ORIGINAL; @Column({ name: 'source_media_id', type: 'bigint', nullable: true }) sourceMediaId: number | null = null; ``` **一行原图 + 多行派生图** 都落在同一张表，用 `variant` 区分，用 `source_media_id` 串起来。 --- ## 变体规格（variantSpecs） 脚本：`code/scripts/generate-place-media-variants.mjs` ```javascript const variantSpecs = { card: 'imageMogr2/thumbnail/900x/format/webp/quality/82', thumb: 'imageMogr2/thumbnail/320x320!/format/webp/quality/75', detail: 'imageMogr2/thumbnail/1280x/format/webp/quality/85', }; ``` | 变体 | COS 处理链 | 典型用途 | |------|------------|----------| | `card` | 宽 900px、WebP、质量 82 | 首页推荐流卡片、列表主图 | | `thumb` | 320×320 裁剪、WebP、质量 75 | 小缩略图、地图 marker | | `detail` | 宽 1280px、WebP、质量 85 | 详情页轮播/大图 | | `original` | 无（上传时保留原格式） | 回退、审核对照、后续再派生 | 参数挂在 **原图 CDN URL 的 query** 上，由 COS 实时处理并返回结果字节流，脚本再 **落盘到独立 object key**，避免每次访问都走实时处理。 --- ## 阶段一：原图入库 脚本：`code/scripts/import-place-media.mjs` ### 做什么 - 读取 `manifest.json` / `manifest.csv`（字段：`place_id`、`local_path` 等） - 默认 **dry-run**；加 `--upload` 才真正 `PUT` 到 COS 并写库 - 按 `sha1` 去重，同一地点同图不重复插入 - 写入时固定 `variant = 'original'` ### Object Key 规则 ```text places/{place_id}/{sha1前12位}_{宽}x{高}.{ext} ``` 派生图使用另一套路径（见下一阶段）： ```text places/{place_id}/variants/{原图id}_{variant}_{sha1前12位}.webp ``` ### 常用命令 ```bash cd code # 试跑：只校验 manifest、算 sha1，不上传 node scripts/import-place-media.mjs \ --manifest ../outputs/place-images-20260524/manifest.json \ --env .env.prod \ --limit 10 # 正式上传 node scripts/import-place-media.mjs \ --manifest ../outputs/place-images-20260524/manifest.json \ --env .env.prod \ --upload ``` ### 环境变量 ```env MEDIA_COS_BUCKET=... MEDIA_COS_REGION=ap-guangzhou MEDIA_COS_SECRET_ID=... MEDIA_COS_SECRET_KEY=... MEDIA_CDN_BASE_URL=https://your-bucket.cos.region.myqcloud.com DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=... DB_PASS=... DB_NAME=liuwapocketmap ``` `putCosObject()` 使用 COS 签名 V1（`q-sign-algorithm=sha1`），从本地文件流式 `PUT` 到 `bucket.cos.region.myqcloud.com`。 --- ## 阶段二：生成派生图 脚本：`code/scripts/generate-place-media-variants.mjs` ### 1. 选出待处理原图 ```sql SELECT id, place_id, object_key, COALESCE(cdn_url, url) AS source_url, ... FROM lwpm_place_media WHERE stage = 'final' AND media_type = 'image' AND variant = 'original' AND review_status = 'approved' AND COALESCE(cdn_url, url) IS NOT NULL ORDER BY id ASC LIMIT ? ``` ### 2. `generateVariant()` 核心步骤 ```javascript async function generateVariant(conn, row, variant, dryRun) { // 幂等：已有同 source + variant 则跳过 const [existing] = await conn.execute( 'SELECT id FROM lwpm_place_media WHERE source_media_id = ? AND variant = ? LIMIT 1', [row.id, variant], ); if (existing.length) return 'skipped'; // 在原图 URL 上拼接 COS 图片处理参数 const sourceUrl = `${row.source_url}${row.source_url.includes('?') ? '&' : '?'}${variantSpecs[variant]}`; const bytes = await fetchBuffer(sourceUrl); const sha1 = crypto.createHash('sha1').update(bytes).digest('hex'); const objectKey = `places/${row.place_id}/variants/${row.id}_${variant}_${sha1.slice(0, 12)}.webp`; const cdnUrl = `${config.cdnBaseUrl}/${objectKey}`; if (dryRun) return 'dry_run'; await putCosObject(objectKey, bytes, 'image/webp'); await conn.execute(`INSERT INTO lwpm_place_media (...) VALUES (...)`); return 'generated'; } ``` 要点： - **处理**：`fetch(原图CDN + imageMogr2 参数)` 拿到 WebP 二进制 - **存储**：`putCosObject` 把结果写到 `variants/` 前缀，与 original 分离 - **关联**：`variant` = `card|thumb|detail`，`source_media_id` = 原图 `id` - **元数据**：脚本内联解析 PNG/WebP 头得到 `width`/`height`，写入 `size_bytes`、`sha1` ### 3. 常用命令 ```bash cd code # 试跑：不 PUT、不写库 node scripts/generate-place-media-variants.mjs \ --env .env.prod \ --limit 50 \ --dry-run # 生成 card + thumb + detail（默认三种全跑） node scripts/generate-place-media-variants.mjs \ --env .env.prod \ --limit 200 # 只补 card node scripts/generate-place-media-variants.mjs \ --env .env.prod \ --variants card \ --limit 500 ``` --- ## 阶段三：后端按场景选图 文件：`code/apps/backend/src/modules/place/place.service.ts` 设计原则：**优先派生图，没有则回退原图**（`NOT EXISTS` 子查询保证不会同时返回原图和其派生图）。 ### 首页 / 公开列表：`card` → `thumb` → `original` 子查询 `image_urls` 逻辑摘要： ```sql AND pm.variant IN ('card','thumb','original') AND ( pm.variant IN ('card','thumb') OR NOT EXISTS ( SELECT 1 FROM lwpm_place_media mv WHERE mv.source_media_id = pm.id AND mv.variant IN ('card','thumb') ... ) ) ORDER BY CASE WHEN pm.role = 'cover' THEN 0 ELSE 1 END, CASE pm.variant WHEN 'card' THEN 0 WHEN 'thumb' THEN 1 ELSE 2 END, pm.sort_order ASC, pm.id ASC ``` 含义： - 若某张原图已有 `card` 或 `thumb` 派生行，**列表里不再暴露这条 `original`** - 若派生图还没生成，**暂时用 `original` 顶上**，业务不中断 - 排序上 `cover` 角色优先，同角色下 `card` 优于 `thumb` 优于 `original` ### 详情页：`detail` → `original` ```sql AND pm.variant IN ('detail','original') AND ( pm.variant = 'detail' OR NOT EXISTS ( SELECT 1 FROM lwpm_place_media mv WHERE mv.source_media_id = pm.id AND mv.variant = 'detail' ... ) ) ORDER BY CASE WHEN role = 'cover' THEN 0 ELSE 1 END, CASE WHEN variant = 'detail' THEN 0 ELSE 1 END, sort_order ASC, id ASC ``` 详情需要更大图，因此单独用 `detail` 变体，回退策略与列表相同。 --- ## 与「实时 COS 处理」的对比 | 方式 | 优点 | 缺点 | |------|------|------| | URL 拼 `imageMogr2` 实时处理 | 不占额外存储 | 每次访问都处理；CDN 缓存键复杂；大图首次慢 | | **本方案：处理一次、写入 variants/** | 接口 URL 稳定；体积可控；易统计 | 需批处理脚本；存储略增 | 本项目选择 **批处理落库**，公开 API 只读固定 `cdn_url`，小程序侧无需关心处理参数。 --- ## 运维检查清单 1. **迁移已执行**：`manual-20260524-add-place-media-variants.sql`（及更早的 COS 扩展迁移） 2. **原图已入库**：`variant='original'` 且 `review_status='approved'` 3. **派生脚本跑完**：按 `source_media_id` + `variant` 查缺补漏 4. **抽查 URL**：`card` 体积应明显小于 `original` 5. **接口验证**：列表 `imageUrls` 首条应为 WebP variants；无派生时仍为原图 ```sql -- 某地点各变体数量 SELECT variant, COUNT(*) AS cnt FROM lwpm_place_media WHERE place_id = '你的place_id' AND stage = 'final' GROUP BY variant; -- 缺 card 派生的原图（待补跑） SELECT o.id, o.place_id, o.cdn_url FROM lwpm_place_media o LEFT JOIN lwpm_place_media c ON c.source_media_id = o.id AND c.variant = 'card' WHERE o.variant = 'original' AND o.stage = 'final' AND o.review_status = 'approved' AND c.id IS NULL LIMIT 20; ``` --- ## 相关文件索引 | 环节 | 路径 | |------|------| | 原图入库脚本 | `code/scripts/import-place-media.mjs` | | 派生图脚本 | `code/scripts/generate-place-media-variants.mjs` | | 变体字段迁移 | `code/database/migrations/manual-20260524-add-place-media-variants.sql` | | COS 字段迁移 | `code/database/migrations/manual-20260524-extend-place-media-for-cos.sql` | | Entity | `code/apps/backend/src/shared/entities/place-media/place-media.entity.ts` | | 公开选图 | `code/apps/backend/src/modules/place/place.service.ts` | | 导入方案（Phase 1） | `code/docs/11-place-media-import-plan.md` | --- ## 小结 - **`original`**：manifest 导入的唯一真相源，先保证能访问。 - **`card` / `thumb` / `detail`**：按场景预生成 WebP，通过 `source_media_id` 挂到原图。 - **API**：用 SQL `NOT EXISTS` 实现「有派生用派生、没有用原图」，上线与批处理解耦。 - **脚本**：`variantSpecs` 集中管理 COS 参数；`generateVariant` + `putCosObject` 负责拉取、上传、幂等写库。 按「导入原图 → 批量派生 → 接口自动切换」三步走，即可在不影响业务的前提下，把小程序图片流量和首屏耗时压下来。 ]]> http://herong.info/posts/开发环境/macOS 本地多 GitHub 账号克隆私有仓库教程 http://herong.info/posts/开发环境/macOS 本地多 GitHub 账号克隆私有仓库教程 Wed, 13 May 2026 11:00:00 GMT 全局 `~/.gitconfig` > 系统配置**。 ### 3. HTTPS 下谁负责认证 带用户名的地址： ```bash https://herongdev@github.com/maxgooder/userweb.git ``` 表示向 GitHub 认证时使用用户名 `herongdev`（配合该账号的 token）。进入仓库后可用： ```bash git remote -v ``` 确认 `origin` 是否已是 `https://herongdev@github.com/...`。若仍是 `https://github.com/...`（无用户名），pull/push 时可能又去钥匙串里「猜」账号，多账号下易乱。 ### 4. 已 clone 后如何固定认证账号 **说明**：下面这条改的是 **访问远程时用的 GitHub 登录身份**，不是「提交账号」。 ```bash git remote set-url origin https://herongdev@github.com/maxgooder/userweb.git ``` 再 `git remote -v` 确认即可。 ### 5. 再克隆同一仓库 同一目录下重复 `git clone ... userweb` 会因目录已存在而失败；可指定新目录名： ```bash git clone https://herongdev@github.com/maxgooder/userweb.git userweb2 ``` 若使用无用户名的 `https://github.com/...`，则仍可能走钥匙串里的任意缓存账号。 ### 6. 推荐固定习惯 ```bash git clone https://herongdev@github.com/maxgooder/userweb.git cd userweb git config user.name "herongdev" git config user.email "该账号已验证邮箱或 noreply 邮箱" git remote -v git config user.name git config user.email ``` --- ## 九、最终结论 本地多 GitHub 账号克隆组织私有仓库时，关键不是只改 `git config user.email`，而是 **GitHub 认证用对了谁**。 HTTPS 下推荐流程： ```text 确认有权限的 GitHub 用户名 → 清理 macOS 钥匙串旧凭据 → 使用 https://用户名@github.com/org/repo.git 克隆 → 输入勾选 repo（及必要时 SSO 授权）的 token → 项目内单独设置 git config user.name / user.email（与账号绑定邮箱一致） ``` 再记一句区分： - **`remote URL` + Token（或 SSH）** → 有没有权限访问仓库。 - **`git config user.name / user.email`** → 提交记录显示谁；GitHub 是否把绿点算到某个用户，主要看 **email 是否绑定在该 GitHub 账号上**。 长期维护多账号，更推荐 **SSH 分 Host + 分密钥**，从根上避开 HTTPS 凭据混用。 ]]> http://herong.info/posts/服务器部署/Nginx location 与 proxy_pass 尾斜杠区别说明 http://herong.info/posts/服务器部署/Nginx location 与 proxy_pass 尾斜杠区别说明 Thu, 14 May 2026 12:00:00 GMT http://herong.info/posts/服务器部署/Ubuntu 22.04 安装 Docker Engine 教程 http://herong.info/posts/服务器部署/Ubuntu 22.04 安装 Docker Engine 教程 Thu, 14 May 2026 00:00:00 GMT /dev/null：不在终端输出 tee 写入的内容，保持终端干净 # < /dev/null </dev/null：把错误信息丢弃，例如 docker 组已存在时不显示错误 # || true：即使 groupadd 失败也继续执行，避免因为 docker 组已存在而中断脚本 sudo groupadd docker 2>/dev/null || true ``` ```bash # sudo：使用管理员权限 # usermod：修改用户信息 # -aG docker：把用户追加加入 docker 组 # -a 表示 append，追加，不覆盖用户原来的组 # -G 表示指定附加用户组 # $USER：当前登录用户名，Shell 会自动替换成你的用户名 sudo usermod -aG docker $USER ``` ```bash # newgrp docker：让当前终端会话立即切换到 docker 组 # 正常情况下，也可以退出 SSH 重新登录，让用户组权限生效 newgrp docker ``` ```bash # docker run：这次不加 sudo 运行容器 # hello-world：测试镜像 # 如果能成功输出 Hello from Docker!，说明当前用户已经可以直接使用 Docker docker run hello-world ``` --- ## 十一、可选：配置 Docker 镜像加速 国内服务器拉取 Docker Hub 镜像经常较慢，可以配置 `registry-mirrors`。Docker 官方说明可以通过编辑 `/etc/docker/daemon.json` 来持久化配置 registry mirror。([Docker Documentation][3]) ```bash # sudo：使用管理员权限 # mkdir：创建目录 # -p：如果上级目录不存在就一起创建；如果目录已存在也不报错 # /etc/docker：Docker daemon 配置目录 sudo mkdir -p /etc/docker ``` ```bash # sudo：使用管理员权限 # tee：把下面的 JSON 内容写入 /etc/docker/daemon.json # /etc/docker/daemon.json：Docker daemon 的配置文件 # > /dev/null：不把写入内容输出到终端 # registry-mirrors：Docker 镜像加速地址配置项 # 注意：这里的 https://你的可用镜像源地址 需要替换成真实可用的镜像源 sudo tee /etc/docker/daemon.json > /dev/null < http://herong.info/posts/架构与工程化/解决 Cursor 占用磁盘 100％ 导致电脑卡顿的完整排坑指南（Windows） http://herong.info/posts/架构与工程化/解决 Cursor 占用磁盘 100％ 导致电脑卡顿的完整排坑指南（Windows） Wed, 22 Oct 2025 00:00:00 GMT 目标：把不必要的扫描与监听“关掉/绕开”，让真实开发 I/O 回到可接受范围。 --- ## 二、整体思路（先做 1 ～ 3） 1. **查凶手**：资源监视器定位哪个进程、哪条路径在疯狂打盘。 2. **杀毒与搜索排除**：把工程与缓存目录从 Defender 和 Windows 搜索索引中排除（对可信仓库）。 3. **限制编辑器索引/监听**：配置 Cursor/VSCode 的 `watcherExclude`、`search.exclude` 等，并优化 `.cursorignore`。 4. **保证 SSD 空间与健康**：预留 15–20% 空间，执行 TRIM/ReTrim，更新固件/驱动。 5. **复测**：活动时间应降到 10–20% 以内，平均响应 < 20ms（空闲更低）。 --- ## 三、分步实现 ### 步骤 1 ｜定位“谁在打磁盘” 1. 打开 **任务管理器 → 进程**，按“**磁盘**”排序。 2. 打开 **资源监视器（resmon）→ 磁盘**： - 看“**具有最大活动时间的进程**”。 - 展开“**磁盘活动**”，观察**文件路径**（常见：`Cursor.exe` / `node.exe` / `TypeScript Server` / `MsMpEng.exe` / 工程目录下的 `node_modules/.next/dist/.git` 等）。 ### 步骤 2 ｜排除杀毒与系统索引（强烈推荐） > 仅对**可信**的代码仓库使用排除。 **以管理员身份**打开 PowerShell，按需替换路径后执行： ```powershell # 在修改处上一行给注释：排除你的工程与常见前端缓存目录 Add-MpPreference -ExclusionPath "D:\work\your-repo","C:\Users\你的用户名\AppData\Local\pnpm-store","C:\Users\你的用户名\AppData\Local\npm-cache","C:\Users\你的用户名\AppData\Local\Cursor" # 在修改处上一行给注释：可选——排除相关进程（减少实时扫描干扰） Add-MpPreference -ExclusionProcess "cursor.exe","node.exe","git.exe" ``` 再到 **设置 → 隐私和安全性 → Windows 搜索**：把你的**工程根目录**加入**不编入索引**的路径。 ### 步骤 3 ｜限制 Cursor/VSCode 的文件监控与索引 在工作区创建/编辑 **`.vscode/settings.json`**： ```jsonc { // 在修改处上一行给注释：停止对大目录的文件系统监控，减少事件风暴 "files.watcherExclude": { "**/node_modules/**": true, "**/.git/**": true, "**/.next/**": true, "**/dist/**": true, "**/.turbo/**": true, "**/build/**": true, "**/.dart_tool/**": true }, // 在修改处上一行给注释：从搜索中排除上述目录，避免频繁全盘扫描 "search.exclude": { "**/node_modules": true, "**/.git": true, "**/.next": true, "**/dist": true, "**/.turbo": true, "**/build": true, "**/.dart_tool": true }, // 在修改处上一行给注释：关闭大仓库的 TS 项目诊断，减轻索引压力 "typescript.tsserver.experimental.enableProjectDiagnostics": false } ``` > **Cursor 专属**：若有 “**Codebase / Repo Map / Embeddings / Index workspace**” 等索引功能，**先关掉**再观察曲线。 ### 步骤 4 ｜完善 `.cursorignore` 你已添加了 `.cursorignore`，建议在“已有规则”基础上补充几条**容易漏掉**的目录（只贴新增/调整部分）： ```gitignore # 在修改处上一行给注释：忽略包管理器全局/本地存储与锁定缓存 .pnpm-store/ npm-cache/ yarn-error.log # 在修改处上一行给注释：忽略 LLM/Embeddings/搜索缓存（若存在） .vector_cache/ .embeddings/ .repo-map/ # 在修改处上一行给注释：忽略临时拉链/导出产物 *.zip *.7z ``` > 你的原始片段已经很完善（见文末“附录 · 配置汇总”），上面仅是**增量补强**。 ### 步骤 5 ｜保证 SSD 空间与健康 - **至少保留 15–20% 空间**（512G 盘建议空出 ≥70–100G）。 - 可删再装：`node_modules/`、`.next/`、`dist/` 等。 - 固件/驱动：更新 **SSD 固件** 与 **主板存储控制器驱动**；设备管理器确认 **AHCI**&开启写缓存。 ### 步骤 6 ｜ TRIM / ReTrim 与快速自检 以管理员身份打开 **命令提示符**： ```cmd :: 在修改处上一行给注释：0 表示已启用 TRIM fsutil behavior query DisableDeleteNotify :: 在修改处上一行给注释：对 SSD 执行 ReTrim defrag C: /L :: 在修改处上一行给注释：简易磁盘状态（仅粗略参考） wmic diskdrive get status ``` ### 步骤 7 ｜（可选）WSL 的工程位置 若使用 WSL，优先把仓库放在 Linux 文件系统（`\\wsl$\\home\...`），避免跨盘随机 I/O。 ### 步骤 8 ｜复测与回归 - 任务管理器里 **C 盘活动时间**应降到 **< 10–20%**； - **平均响应时间**应回落到 **< 20ms**。 若仍异常：回到**资源监视器 → 磁盘**，按“**文件**”列定位残余热路径，针对性再加排除/忽略。 --- ## 四、一分钟速览清单（可直接照做） 1. 资源监视器锁定**进程 + 路径**。 2. PowerShell 执行 `Add-MpPreference -ExclusionPath ...` 与 `-ExclusionProcess ...`。 3. `.vscode/settings.json` 配置 `files.watcherExclude` 与 `search.exclude`。 4. `.cursorignore` 覆盖常见大目录与缓存。 5. 保留 ≥15% SSD 空间，执行 `defrag C: /L`，更新固件与驱动。 6. 复测活动时间与响应时间。 --- ## 五、常见问答 **Q1：为什么活动时间 100% 但带宽只有几 MB/s？** A：因为都是**小文件随机 I/O**，磁盘在“排队”等寻道/擦写，**延迟**而非**吞吐**成了瓶颈。 **Q2：排除杀毒会不会不安全？** A：仅对**可信仓库与缓存目录**排除即可，保持系统盘与下载区常规防护。 **Q3：.cursorignore 与 .gitignore 要一样吗？** A：高度重叠但不必完全一致。`.cursorignore` 关注“**不参与索引/上下文**”，可更激进些；`.gitignore` 关注版本管理。 --- ## 六、附录 · 可复制的脚本与配置汇总 ### 1）PowerShell（管理员） ```powershell # 在修改处上一行给注释：排除工程与缓存目录（请替换为你的真实路径） Add-MpPreference -ExclusionPath "D:\work\your-repo","C:\Users\你的用户名\AppData\Local\pnpm-store","C:\Users\你的用户名\AppData\Local\npm-cache","C:\Users\你的用户名\AppData\Local\Cursor" # 在修改处上一行给注释：可选——排除相关进程 Add-MpPreference -ExclusionProcess "cursor.exe","node.exe","git.exe" ``` ### 2）`.vscode/settings.json` ```jsonc { // 在修改处上一行给注释：限制文件系统监控 "files.watcherExclude": { "**/node_modules/**": true, "**/.git/**": true, "**/.next/**": true, "**/dist/**": true, "**/.turbo/**": true, "**/build/**": true, "**/.dart_tool/**": true }, // 在修改处上一行给注释：限制全局搜索 "search.exclude": { "**/node_modules": true, "**/.git": true, "**/.next": true, "**/dist": true, "**/.turbo": true, "**/build": true, "**/.dart_tool": true }, // 在修改处上一行给注释：减轻 TS 索引 "typescript.tsserver.experimental.enableProjectDiagnostics": false } ``` ### 3）`.cursorignore`（在你已配置基础上的推荐完整版） ```gitignore # Dependencies node_modules/ .pnp .pnp.js # Build outputs dist/ dist-ssr/ build/ out/ .next/ # Cache directories .cache/ .temp/ .tmp/ .turbo/ .pnpm-store/ npm-cache/ # Test coverage coverage/ .nyc_output/ # Logs logs/ *.log yarn-error.log # OS files .DS_Store Thumbs.db # IDE .vscode/ .idea/ # Generated files components.d.ts auto-imports.d.ts *.tsbuildinfo # LLM / Embeddings（如 Cursor 生成） .vector_cache/ .embeddings/ .repo-map/ # Assets（如很大） # public/pdfpreview/ dist.zip *.zip *.7z # Docs build docs/.vitepress/dist/ docs/.vitepress/cache/ ``` ### 4）SSD 维护（CMD 管理员） ```cmd fsutil behavior query DisableDeleteNotify defrag C: /L wmic diskdrive get status ``` --- ## 七、结语 上述流程兼顾**快速止损**与**长期稳态**：先找元凶、再“减扫描 + 减监听”，最后做 SSD 维护。按文中顺序执行后，Cursor 引起的卡顿通常能显著缓解或彻底消失。若你有特殊路径仍在高频读写，把那条路径贴出来，我再帮你做**精确化排除**。 ]]> http://herong.info/posts/运维/App 审核慢于后端发布时，如何做版本兼容治理 http://herong.info/posts/运维/App 审核慢于后端发布时，如何做版本兼容治理 Sun, 19 Apr 2026 10:00:00 GMT = 3.8.0` - 按能力开：只给支持 `profile_schema_v2` 的客户端 - 按用户比例开：1%、5%、20%、100% - 按用户白名单开：测试账号、内部账号 - 按地区 / 渠道开：需要时使用 --- ## 六、发布流程改成“两阶段”，而不是“一次性上线” 这一步特别重要。 ### 阶段 A：先上兼容后端 这一版后端要满足： - 旧 App 调用时不报错 - 新 App 调用时能拿到新能力 - 新开关默认关闭 - 数据库先扩字段，不删旧字段 - 服务端允许新旧 DTO / VO 并存 ### 阶段 B：等 App 生效后，再开启新能力 等审核通过、灰度包覆盖率上来后，再逐步启用： - 先给测试用户 - 再给 1% - 再给 5% - 再给 20% - 最后全量 Apple 的 phased release 文档明确给出了 7 天放量节奏：1%、2%、5%、10%、20%、50%、100%，而且可以暂停后继续。([Apple Developer][1]) 所以你们要建立一个基本认知： **客户端上线不是一个点，而是一段时间。** 因此后端兼容期也必须覆盖这一段时间，而不是“后端今天发了，明天就删旧逻辑”。 --- ## 七、真遇到破坏性变更时，不要偷偷改老接口，直接升 API 版本 有些需求本身就不适合兼容： - 返回结构必须重做 - 核心字段语义必须改变 - 老流程必须下线 - 老客户端根本无法理解新协议 这时候不要继续强行改 `/api/v1/...`，而应该： - 保留 `/api/v1/...` - 新增 `/api/v2/...` 或者通过请求头区分 API 版本。 Google AIP-185 专门规定了 Google API 的版本策略；Stripe 也明确区分 major release 和兼容式月度发布；Microsoft Graph 也有独立的版本支持和 breaking change 策略。([Google AIP][5]) ### 一个简单判断标准 #### 不升版本，继续兼容 适用于： - 新增字段 - 新增可选参数 - 新增非破坏性接口 - 新逻辑可以按开关控制 #### 升版本 适用于： - 删除字段 - 字段改名 - 字段类型变化 - 响应结构重做 - 参数规则发生不兼容变化 - 旧端无法继续正确解析 --- ## 八、最低支持版本和强制升级，只在少数场景用 很多团队一遇到兼容问题，就想“那就强制升级”。 这个手段能用，但不要滥用。 ### 适合强制升级的场景 - 安全漏洞 - 合规风险 - 资金结算风险 - 旧协议会导致严重数据错误 - 某些核心能力必须整体升级才能保证业务正确性 ### 不适合强制升级的场景 - 普通功能调整 - 页面样式变化 - 一个字段结构优化 - 新功能刚上线想偷懒不做兼容 也就是说，**强制升级是兜底方案，不是日常方案**。 --- ## 九、观测一定要按“客户端版本”分桶 没有观测，兼容治理最后一定会失效。 至少要统计这些： - 接口错误率：按 `platform + appVersion + buildNumber` - 新旧接口调用量占比 - 某个 capability 的覆盖率 - 新状态 / 新字段触发后的错误率 - Crash 率按客户端版本分布 - 某个老版本的活跃用户量 Firebase 的 rollout 文档本身就强调：要结合 Crashlytics 和 Analytics 来衡量 rollout 的稳定性和成功情况。([Firebase][4]) 只有拿到这些数据，你们才敢回答下面这些问题： - 旧兼容逻辑什么时候能删？ - 某个版本是不是还在线上大量活跃？ - 某次异常是不是只出现在旧 App？ - 新开关是否可以从 5% 放到 20%？ --- ## 十、推荐的服务端架构：加一层 BFF 或网关适配 如果你们现在是： - Web 直接调业务后端 - App 直接调业务后端 - 页面字段和后端结构强耦合 那后面兼容成本会越来越高。 更稳的方式是： - App / Web → BFF / API Gateway - BFF / Gateway → 内部业务服务 BFF 层专门负责： - 读取客户端版本 / 能力 - 新旧字段映射 - 旧端返回旧结构 - 新端返回新结构 - feature flag 决策 - 降级与兜底 这样内部服务可以更专注于业务，客户端兼容策略集中在边界层处理。 --- ## 十一、分步落地方案 下面给你一个适合多数团队的落地步骤。 ### 第一步：定义接口兼容红线 先把团队规范写清楚： - 允许：新增接口、新增可选字段、新增可选参数 - 禁止：删字段、改名、改类型、改必填、改语义 这一步没有做，后面都会乱。 ### 第二步：统一客户端请求元数据 网关层统一解析： - platform - appVersion - buildNumber - apiVersion - capabilities 然后挂到统一的 `ClientContext` 上，后端各业务服务统一使用，不要每个接口手写一套版本判断。 ### 第三步：所有新功能必须挂开关 凡是 App 相关需求，默认都要支持： - 关闭 - 指定版本开启 - 按能力开启 - 按比例灰度 ### 第四步：改发布流程 以后涉及 App 的需求，固定流程改成： 1. 后端先上兼容版本 2. 开关默认关闭 3. App 提审 4. 审核通过后灰度启用 5. 观察监控 6. 放量 7. 老逻辑进入弃用期 8. 覆盖率足够后再删除 ### 第五步：建立弃用周期 不要“新版本一上，老逻辑立刻删”。 应该有一个明确的弃用窗口，例如： - 发布公告日期 - 新客户端最低覆盖率目标 - 旧接口停止写入时间 - 旧接口彻底下线时间 --- ## 十二、最简代码示例 下面只给最小必要示例，方便你们先把机制搭起来。 ### 1）客户端请求头 ```ts // 请求时统一带上客户端元数据 const headers = { "X-Client-Platform": "ios", "X-App-Version": "3.8.1", "X-Build-Number": "20260419", "X-Api-Version": "v1", "X-Capabilities": ["order_cancel_v2", "profile_schema_v2"].join(","), }; ``` ### 2）服务端解析 ClientContext ```ts export interface ClientContext { platform: "ios" | "android" | "web" | "unknown"; appVersion: string; buildNumber: string; apiVersion: string; capabilities: string[]; } export function parseClientContext( headers: Record, ): ClientContext { const capabilityHeader = headers["x-capabilities"]; const capabilityValue = Array.isArray(capabilityHeader) ? capabilityHeader[0] : capabilityHeader; return { platform: normalizePlatform(headers["x-client-platform"]), appVersion: getSingleHeader(headers["x-app-version"]), buildNumber: getSingleHeader(headers["x-build-number"]), apiVersion: getSingleHeader(headers["x-api-version"]) || "v1", capabilities: capabilityValue ? capabilityValue .split(",") .map((item) => item.trim()) .filter(Boolean) : [], }; } function getSingleHeader(value: string | string[] | undefined): string { if (Array.isArray(value)) return value[0] || ""; return value || ""; } function normalizePlatform( value: string | string[] | undefined, ): ClientContext["platform"] { const platform = getSingleHeader(value).toLowerCase(); if (platform === "ios") return "ios"; if (platform === "android") return "android"; if (platform === "web") return "web"; return "unknown"; } ``` ### 3）服务端不要直接按版本号硬切，优先按能力判断 ```ts export function supportsCapability( clientContext: ClientContext, capability: string, ): boolean { return clientContext.capabilities.includes(capability); } ``` ```ts // 这里先判断 capability，再决定返回新旧结构，避免旧 App 直接拿到无法解析的数据 export function buildProfileResponse( clientContext: ClientContext, user: { id: string; nickname: string; avatar: string }, ) { if (supportsCapability(clientContext, "profile_schema_v2")) { return { userId: user.id, profile: { nickname: user.nickname, avatar: user.avatar, }, }; } return { id: user.id, nickname: user.nickname, avatar: user.avatar, }; } ``` ### 4）Feature Flag 决策示例 ```ts export interface FeatureFlagRule { featureKey: string; enabledPlatforms: string[]; minAppVersionByPlatform: Record; requiredCapability?: string; } export function isFeatureEnabled( clientContext: ClientContext, rule: FeatureFlagRule, ): boolean { if (!rule.enabledPlatforms.includes(clientContext.platform)) { return false; } const minVersion = rule.minAppVersionByPlatform[clientContext.platform]; if (minVersion && compareVersion(clientContext.appVersion, minVersion) < 0) { return false; } // 这里额外叠加 capability 判断，避免某些渠道包版本号满足但实际能力未接入 if ( rule.requiredCapability && !supportsCapability(clientContext, rule.requiredCapability) ) { return false; } return true; } ``` ```ts export function compareVersion(current: string, target: string): number { const currentParts = current.split(".").map(Number); const targetParts = target.split(".").map(Number); const maxLength = Math.max(currentParts.length, targetParts.length); for (let index = 0; index < maxLength; index += 1) { const currentValue = currentParts[index] || 0; const targetValue = targetParts[index] || 0; if (currentValue > targetValue) return 1; if (currentValue < targetValue) return -1; } return 0; } ``` ### 5）控制器里使用 ```ts // 这里把客户端上下文放在入口层统一解析，业务层只消费标准化后的 ClientContext const clientContext = parseClientContext(req.headers); const profileFeatureRule = { featureKey: "profile_v2", enabledPlatforms: ["ios", "android"], minAppVersionByPlatform: { ios: "3.8.0", android: "3.8.0", }, requiredCapability: "profile_schema_v2", }; if (isFeatureEnabled(clientContext, profileFeatureRule)) { return buildProfileResponse(clientContext, user); } return buildProfileResponse( { ...clientContext, capabilities: [], }, user, ); ``` --- ## 十三、一个最容易执行的团队规范模板 你们可以直接把下面这几条定成规范。 ### 接口规范 - 普通迭代只允许 additive change - 破坏性变更必须升 `v2` - 不允许在 `v1` 原地做不兼容修改 ### 客户端规范 - 所有请求必须上报 `platform / appVersion / buildNumber / apiVersion / capabilities` - 新功能接入后必须登记 capability 名称 - 旧版本必须对未知字段、未知枚举做兜底 ### 发布规范 - 先发兼容后端 - 再发客户端 - 审核通过后开灰度 - 监控通过后再全量 - 旧逻辑不得在客户端全量前删除 ### 运维规范 - 错误率必须按客户端版本分桶 - 开关必须支持快速关闭 - 旧接口下线前必须看活跃覆盖率 --- ## 十四、结论 如果只让我给一句最核心的建议，那就是： **把旧客户端当成长期存在的真实依赖，而不是一个“过两天就没人用了”的临时问题。** 一旦按这个前提设计，你们的方案自然就会变成： - 默认兼容式演进 - 客户端上报能力 - 新功能先挂开关 - 发布分两阶段 - 破坏性变更走版本化 - 下线旧逻辑依赖真实覆盖率数据 这套方式，既适合你们现在的 Web + 后端 + App 并行迭代，也和公开的大厂 API 治理、移动端灰度发布思路一致。([Stripe Docs][2]) --- ## 参考资料 - Stripe API Versioning：月度发布保持 backward-compatible，major release 才承载不兼容变更。([Stripe Docs][2]) - Microsoft Graph Versioning and Support：对 breaking changes 和版本支持有明确策略。([Microsoft Learn][6]) - Google AIP-185 / AIP-181：规定 API versioning 策略，并强调稳定 API 中原地做 breaking change 应极其谨慎。([Google AIP][5]) - Firebase Remote Config Rollouts：支持按参数作为 feature flags 进行渐进发布，并结合 Crashlytics / Analytics 观察效果。([Firebase][4]) - Apple Phased Release：7 天分阶段放量，且用户仍可手动更新。([Apple Developer][1]) 你要是愿意，我下一条可以继续直接给你一篇 **“适合 NestJS 项目的版本兼容治理落地方案”**，我会按同样的 Hexo 格式写，并且把中间件、`ClientContext`、Feature Flag、接口版本目录结构都补出来。 [1]: https://developer.apple.com/help/app-store-connect/update-your-app/release-a-version-update-in-phases/?utm_source=chatgpt.com "Release a version update in phases - Update your app" [2]: https://docs.stripe.com/api/versioning?utm_source=chatgpt.com "Versioning | Stripe API Reference" [3]: https://google.aip.dev/181?utm_source=chatgpt.com "AIP-181: Stability levels" [4]: https://firebase.google.com/docs/remote-config/rollouts?utm_source=chatgpt.com "Remote Config rollouts - Firebase" [5]: https://google.aip.dev/185?utm_source=chatgpt.com "AIP-185: API Versioning" [6]: https://learn.microsoft.com/en-us/graph/versioning-and-support?utm_source=chatgpt.com "Versioning, support, and breaking change policies for ..." ]]> http://herong.info/posts/运维/ssl https 证书过期 http://herong.info/posts/运维/ssl https 证书过期 Mon, 13 Apr 2026 00:00:00 GMT /dev/null \ | openssl x509 -noout -dates -subject -issuer ``` （可补充：浏览器「证书详情」、云平台证书控制台、监控告警里的字段说明。） ### 需要核对的信息 - 域名与 **SAN** 是否覆盖当前访问名 - **颁发者**（自签 / 商业 CA / Let's Encrypt 等） - **Not Before / Not After** 与服务器时区、NTP 是否一致 --- ## 根因归类（便于选对续期方式） | 情况 | 常见原因 | 处理方向 | | --------------------------- | --------------------------- | ---------------------------- | | 例：单台 Nginx 静态证书文件 | 文件到期未替换 | 重新签发 → 替换文件 → reload | | 例：K8s Ingress / 网关 | Secret 未更新或控制器未拉新 | 更新 Secret / 检查控制器日志 | | 例：云负载均衡 | 控制台证书过期 | 在 CLB/ALB 上绑定新证书 | | （按需增行） | | | --- ## 续期与替换：操作步骤 > 按你的实际栈**只保留一节**写细，其余可删或链到别文。 ### 方案 A：（例如 Let's Encrypt / ACME + certbot） 1. （前置条件：80/443、DNS、机器权限） 2. （签发或 renew 命令） 3. （证书路径、服务 reload 命令） ### 方案 B：（例如云厂商证书 + 一键部署到 CDN/LB） 1. （在控制台申请/上传）：重新申请，申请时会生成新的txt，域名解析那里也要同步个性；下载新的证书，放到nginx中指定的目录；要重启nginx; 2. （绑定到监听器/域名） 3. （传播与缓存：CDN、边缘节点） ### 方案 C：（例如内网 PKI / 自签） 1. （CA 与叶子证书签发流程） 2. （信任链安装到客户端或服务） 3. （轮换策略） --- ## 验证 - `curl -vI https://你的域名` 或 openssl 再次查看 `notAfter` - 浏览器隐私模式访问，确认无证书警告 - （若有）灰度节点、多地域、CDN 各做一次抽样 --- ## 回滚与应急 - 旧证书文件是否仍保留、如何一键切回 - 若新证书链不完整导致部分客户端失败，如何快速换回 --- ## 预防：监控与自动化 - 到期前 **N 天** 告警（监控项、阈值、通知渠道） - 自动续期任务（cron / systemd timer / 云函数）及 **失败告警** - 变更记录：谁、何时、换了哪张证、关联哪些入口 --- ## 附录：本次变更记录（可选） | 项目 | 内容 | | ------------- | --------------------------------- | | 域名 / 入口 | | | 原到期日 | | | 新到期日 | | | 涉及组件 | （Nginx / Ingress / CLB / CDN …） | | 操作人 / 时间 | | --- ## 参考 - （官方文档链接） - （团队内部 runbook 链接） ]]> http://herong.info/posts/运维/一次讲明白 CSP：为什么 iframe 小组件会被浏览器拦截 http://herong.info/posts/运维/一次讲明白 CSP：为什么 iframe 小组件会被浏览器拦截 Fri, 24 Apr 2026 00:00:00 GMT 服务器告诉浏览器：这个页面允许加载哪些来源的脚本、图片、样式、字体、接口、iframe 等资源。 所以 CSP 不是后端业务逻辑，也不是前端框架功能，而是一个**浏览器安全策略**。 你这次的问题，本质是： ```txt 页面想加载 iframe： https://gtchome.returning.ai/ 但是当前页面的 CSP 只允许加载自己站点的资源： default-src 'self' data: 所以浏览器直接拦截 iframe。 ``` MDN 对 `default-src` 的说明是：它会作为其他资源指令的兜底规则；如果更具体的规则没有写，浏览器就会用 `default-src` 来判断是否允许加载。([MDN Web Docs][1]) # 二、CSP 是在哪里生效的？ CSP 通常是通过 HTTP 响应头下发的。 比如你现在看到的： ```http content-security-policy: default-src 'self' 'unsafe-inline' 'unsafe-eval' data:; img-src * data:; font-src * data:; ``` 这表示服务器返回页面或资源时，顺便告诉浏览器： ```txt 这个页面默认只能加载自己站点的资源； 图片可以任意来源； 字体可以任意来源； 但 iframe 没有单独放行规则。 ``` 重点是：**CSP 是浏览器执行的。** 服务器只是返回这个规则，真正拦截资源的是浏览器。 所以排查时要看： ```txt DevTools → Network → 主页面请求 → Response Headers → Content-Security-Policy ``` 如果这里有 CSP，浏览器就会按它来执行。 # 三、几个最常见的 CSP 指令 ## 1. default-src ```http default-src 'self' data: ``` 它是默认规则。 如果某类资源没有专门配置，比如没有写 `frame-src`，浏览器就会退回使用 `default-src`。 你的错误里这句话非常关键： ```txt Note that 'frame-src' was not explicitly set, so 'default-src' is used as a fallback. ``` 翻译一下就是： ```txt 你没有配置 frame-src，所以我用 default-src 来判断 iframe。 ``` 而你的 `default-src` 里面没有： ```txt https://gtchome.returning.ai ``` 所以 iframe 被拦截。 ## 2. img-src ```http img-src * data: ``` 控制图片来源。 这表示图片可以从任意来源加载，也可以加载 base64 / data URL。 ## 3. font-src ```http font-src * data: ``` 控制字体来源。 这表示字体可以从任意来源加载。 ## 4. script-src ```http script-src 'self' ``` 控制 JavaScript 脚本来源。 你当前响应头里没单独写 `script-src`，所以脚本也会走 `default-src`。 但是你现在的 CSP 写了： ```http default-src 'self' 'unsafe-inline' 'unsafe-eval' data: ``` 所以内联脚本、`eval` 这类危险能力也被允许了。 从安全角度看，这不是很理想，但这是另一个问题。 ## 5. frame-src ```http frame-src 'self' https://gtchome.returning.ai ``` 控制**当前页面允许嵌入哪些 iframe**。 MDN 对 `frame-src` 的说明是：它用于指定页面中的 ``、`