Instant 十二月版本更新解读：order 排序查询、Sign in with Apple 与默认类型安全 init

后端数据库【免费下载链接】instantInstant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.项目地址https://gitcode.com/gh_mirrors/inst/instant点击查看免费下载这份 2024 年 12 月的 Instant 官方月度更新仓库内原文见 client/www/_emails/markdown/dec2024.md集中宣告了三项面向开发者的能力升级从0.17.0起开放基于类型检查与索引属性的order排序查询新增 Sign in with Apple 登录支持覆盖 Web Popup、Web Redirect 与 React Native 三种流程以及把类型安全的init变为默认行为并保持向后兼容。本文以这三项更新为主线结合仓库内的官方文档与核心源码逐一给出可直接落地的用法、配置步骤与原理说明读完即可在你的 Instant 应用里用上排序查询、Apple 登录和带 schema 的类型安全初始化。一、Order by attributes从固定排序到任意可索引属性排序此前 Instant 的查询只能按serverCreatedAt排序其余字段无法进入order子句根本原因是没有一种让order查询保持高性能的实现路径。随着类型检查属性type checked attributes机制的引入这条路径被打通了从0.17.0开始order可以作用于类型检查过且已建索引indexed的属性。完整语法与示例见仓库官方文档 instaql 查询文档 的 Ordering 小节以下是文档中的核心用法。1. 默认排序与serverCreatedAt文档明确查询的默认排序是对象被创建时间的升序ascending。要改变排序在命名空间的选项映射option map中使用order键const query { todos: { $: { limit: 10, // 与 limit 类似目前 order 仅支持顶级命名空间 order: { serverCreatedAt: desc, }, }, }, };serverCreatedAt是保留键reserved key表示对象第一次被持久化到 Instant 后端的时间可取值asc默认或desc。2. 按索引 类型检查的属性排序除了保留键还可以按任意已建索引且已做类型检查的属性排序。给属性添加索引与检查类型可在 Instant 控制台的 Explorer 中操作或通过 CLI 完成见 CLI 文档。示例获取接下来到期的 todos。// 获取即将到期的 todos const query { todos: { $: { limit: 10, where: { dueDate: { $gt: Date.now() }, }, order: { dueDate: asc, }, }, }, };3. 嵌套命名空间排序与限制order同样支持嵌套命名空间。下面这个查询会拿到 goals 及其关联的 todos并按dueDate升序排列// 获取 goals 及其按到期时间排序的 todos const query { goals: { todos: { $: { order: { dueDate: asc, }, }, }, }, };需要注意一个与where不同、容易踩坑的边界order不支持嵌套属性。如果 todos 拥有 owner你无法用owner.name排序而where恰恰支持对嵌套属性过滤// ❌ order 不支持嵌套属性 const query { todos: { $: { order: { owner.name: asc, // 不能按嵌套属性排序 }, }, }, }; // ✅ where 支持对嵌套属性过滤 const query { todos: { $: { where: { owner.name: a, // 可以按嵌套属性过滤 }, }, }, };4. 源码侧印证类型系统如何支撑排序与过滤order能力之所以与类型检查绑定是因为查询的类型推导完全建立在对属性可比较、可索引的静态约束上。在核心包 client/packages/core/src/queryTypes.ts 中可以看到where子句的值类型被建模为WhereClauseValueComplex它为数值/字符串属性提供了$in、$ne、$gt、$lt、$gte、$lte等比较操作符并为字符串额外提供$like、$ilike为可空属性提供$isNull——这些运算符的合法性都由属性的类型定义DataAttrDef中的值类型、可空、索引标记在编译期推导。配合 modeling-data 数据建模文档 中的约束声明方式可以直观理解类型检查 索引如何成为order/范围过滤的前提email: i.string().unique().indexed(), // 唯一且建索引 price: i.number().indexed(), // 索引属性可配合比较运算符使用 slug: i.string().unique(), // 唯一约束由 Instant 后端保证从实现结构看如 client/packages/core/src/SyncTable.ts 与 client/packages/core/src/infiniteQuery.ts 中均引用serverCreatedAtserverCreatedAt是贯穿查询与同步层的保留字段这也解释了为何它能作为默认排序键存在。二、Sign in with Apple三种流程完整接入Instant 此前已支持 magic code、Google、Clerk 以及通过 Admin SDK 实现的自定义认证流程十二月更新补齐了 Apple 登录并一次性提供三种形态Web Popup推荐、Web Redirect、React Native原生。完整分步指南见 Sign in with Apple 官方文档。三种流程的前两步是共通的需要在 Apple Developer 后台完成配置Step 1创建 App ID进入 Apple Developer 的 Certificates, Identifiers Profiles 页面选择Identifiers→ 点击Register a new identifier→ 选择App IDsSelect a type→ 选择App在Capabilities中勾选Sign In with Apple填写Bundle ID和Description点击Register。Step 2创建 Services ID进入 Services IDs 列表点击Register a new identifier→ 选择Services IDs填写Description和Identifier这个 Identifier 后续配置会用点击Register。Web Popup 流程推荐Step 3 配置 Services ID选中刚创建的 Services ID启用Sign In with Apple点击Configure选择 Step 1 的Primary App ID在Domains中添加你的应用域名如myapp.com在Return URLs中添加应用实际完成认证的 URL如https://myapp.com/signin最后Continue→Save。Step 4 在 Instant 注册 OAuth 客户端在 Instant 控制台的 Auth 标签页点击 Add Apple Client填写唯一的 client name默认apple供后续db.auth调用使用和 Step 2 的 Services ID也可以直接用 CLI 完成npx instant-clilatest auth client add \ --type apple --name apple --services-id services-idStep 5 前端接入引入 Apple 官方登录库用 Services ID 初始化再通过db.auth.signInWithIdToken把 Apple 签发的 id_token 连同 nonce 交给 Instantasync function signInPopup() { let nonce crypto.randomUUID(); // 1. 与 Apple 完成认证 let resp await AppleID.auth.signIn({ nonce: nonce, usePopup: true, }); // 2. 与 Instant 完成认证 await db.auth.signInWithIdToken({ clientName: clientName, idToken: resp.authorization.id_token, nonce: nonce, }); } // 3. 绑定登录按钮 button onClick{signInPopup}Sign In with Apple/buttonWeb Redirect 流程Step 3 配置差异Domains填api.instantdb.comReturn URLs填https://api.instantdb.com/runtime/oauth/callback。Step 3.5 生成私钥在 Keys 页面点击填写名称与描述勾选Sign in with AppleConfigure 中选择 Step 1 的 App ID注册后下载 key 文件。Step 4 注册客户端相比 Popup 流程多出 Team ID、Key ID 与 Private Key 三项配置npx instant-clilatest auth client add \ --type apple --name apple \ --services-id services-id \ --team-id team-id --key-id key-id \ --private-key-file path-to-key.p8Step 4.5 白名单域名Redirect 流程要求把你的应用域名加入 Instant 的允许来源列表npx instant-clilatest auth origin add --type website --url myapp.comStep 5 前端接入通过db.auth.createAuthorizationURL生成授权链接用户点击后由 Instant 后端完成重定向回调const authUrl db.auth.createAuthorizationURL({ clientName: clientName, redirectURL: window.location.href, }); a href{authUrl}Sign In with Apple/aReact Native 流程Instant 内置对 Expo AppleAuthentication 库的支持Expo 无需执行 Step 3 的 Services ID 配置。npx expo install expo-apple-authentication在app.json中开启原生能力{ expo: { ios: { usesAppleSignIn: true } } }开发阶段需要把exp://注册为重定向来源便于 Expo 开发环境npx instant-clilatest auth origin add --type custom-scheme --scheme exp://随后用 Expo API 取得identityToken连同 nonce 一起交给 Instantconst [nonce] useState( Math.random()); try { const credential await AppleAuthentication.signInAsync({ requestedScopes: [ AppleAuthentication.AppleAuthenticationScope.FULL_NAME, AppleAuthentication.AppleAuthenticationScope.EMAIL, ], nonce: nonce, }); db.auth .signInWithIdToken({ clientName: clientName, idToken: credential.identityToken, nonce: nonce, }) .catch((err) { console.log(Error, err.body?.message, err); }); } catch (e) { if (e.code ERR_REQUEST_CANCELED) { // 处理用户取消登录流程 } else { // 处理其他错误 } }完整示例含SignedIn/SignedOut状态组件与登出逻辑见 Apple 登录文档 的 React Native 小节其中db.auth.signOut()用于退出登录db.useUser()用于读取当前用户。在核心包 client/packages/core/src/index.ts 中可以确认signInWithIdToken是 Auth 客户端对外暴露的标准方法clientName参数正是用来匹配你在控制台或 CLI 注册的 Apple client。三、Type-safe init by defaultinit_experimental时代的终结上个月 Instant 在后端上线了类型强制type enforcement本月则把类型安全的init变为默认。此前前端要获得类型安全必须走单独的init_experimental流程现在只需要导入 schema 并直接传给init即可。官方文档见 初始化文档。1. 基本初始化接入 Instant 的第一步是调用initimport { init } from instantdb/react; // Instant app const APP_ID __APP_ID__; const db init({ appId: APP_ID }); function App() { return Main /; }拿到db之后即可用它执行 写入数据instaml、查询instaql、认证 等操作。2. 类型安全初始化新默认使用 TypeScript 时init接受schema参数。提供 schema 后查询与事务都会获得自动补全和类型安全import { init, i } from instantdb/react; // Instant app const APP_ID __APP_ID__; const schema i.schema({ entities: { $files: i.entity({ path: i.string().unique().indexed(), url: i.any(), }), $users: i.entity({ email: i.string().unique().indexed(), }), todos: i.entity({ text: i.string(), done: i.boolean(), createdAt: i.number(), }), }, }); const db init({ appId: APP_ID, schema });schema 的完整写法见 数据建模文档。推荐把db实例放在独立工具文件中导出避免在多个组件里重复初始化// lib/db.ts import { init } from instantdb/react; import schema from ../instant.schema; // Instant app const APP_ID __APP_ID__; export const db init({ appId: APP_ID, schema }); // app/page.tsx use client; import { db } from ../lib/db; function App() { // 查询带类型安全与自动补全 db.useQuery({ todos: {} }); } export default App;Instant 对同一 appId 只会维护一条连接因此即使多次调用init也不会产生多余连接或性能开销见 初始化文档 的 Flexible Initialization 小节。3. 向后兼容init_experimental的废弃路径这次改动是向后兼容的。源码层面给出了最直接的证据在核心包 client/packages/core/src/index.ts 中init_experimental已被标记为deprecated并且实现就是init本身/** * deprecated * init_experimental is deprecated. You can replace it with init. * * example * * // Before * import { init_experimental } from instantdb/core * const db init_experimental({ ... }); * * // After * import { init } from instantdb/core * const db init({ ... }); */ const init_experimental init;也就是说升级到最新版本后旧代码继续运行但新代码应统一使用init并迁移掉init_experimental引用。4.init的完整配置项初始化文档 列出了init支持的全部选项除appId与schema外还包括appId必填你的 InstantDB 应用 ID用于连接对应后端schema?来自instant.schema.ts的 schema 导出提供查询、事务与 ephemeral 特性的类型安全websocketURI?实时连接的 WebSocket 端点默认wss://api.instantdb.com/runtime/session连接开发或自托管实例时修改apiURI?认证与存储的 HTTP API 端点默认https://api.instantdb.comdevtool?控制 Instant 开发工具localhost 下默认开启可设为false关闭或配置position、allowedHosts、dashURI自托管 dashboard 时设置verbose?开启详细控制台日志WebSocket 消息与内部操作便于排查连接与同步问题logger?自定义verbose输出方式提供debug、info、error方法默认console仅在verbose为true时生效queryCacheLimit?离线模式缓存的查询订阅数量上限默认10缓存的查询可在应用重载时立即呈现数据useDateObjects?为true时查询中的日期列返回 JavaScriptDate对象默认关闭。四、小结三个特性如何串联起类型优先的开发体验回看十二月这批更新一条主线非常清晰类型系统正在成为 Instant 各项能力的公共地基。order查询的开放依赖类型检查 索引属性的存在类型安全init的默认化让 schema 成为前端开发的一等公民而 Apple 登录这类新认证流程则进一步夯实了开箱即用的后端能力。三者叠加后开发者可以用更少的样板代码同时获得更快的排序查询、更完整的登录矩阵与编译期的类型保障。上述全部能力均可在当前仓库对应文档与源码中逐一验证升级到最新版本即可按本文步骤直接使用。赞分享后端数据库【免费下载链接】instantInstant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.项目地址https://gitcode.com/gh_mirrors/inst/instant点击查看免费下载相关推荐国家中小学智慧教育平台电子课本PDF怎么下载三步解析保存完整指南国家中小学智慧教育平台电子课本PDF怎么下载三步解析保存完整指南 国家中小学智慧教育平台上的课本只能在线看找不到下载入口tchMaterial parse网页爬虫教育Instant 接入 Sign In with Apple 完整指南Web Popup、Web Redirect 与 React Native 三种流程实战Instant 接入 Sign In with Apple 完整指南Web Popup、Web Redirect 与 React Native 三种流程实战后端数据库探索Sign in with Apple Unity插件简化Apple登录体验探索Sign in with Apple Unity插件简化Apple登录体验 在数字世界的快速演变中用户身份验证始终是开发者关注的焦点。随着Apple在W上一篇IOPaint PowerPaint V25分钟上手AI图片修复去路人、去水印、去文字全都会下一篇generative-ai-for-beginners 第6课基于 OpenAI 客户端与 Responses API 构建文本生成应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考