前端后端移动开发【免费下载链接】amplify-jsA declarative JavaScript library for application development using cloud services.项目地址https://gitcode.com/gh_mirrors/am/amplify-js点击查看免费下载packages/analytics/CHANGELOG.md记录了 AWS Amplify JavaScript 库中 Analytics 类别从 1.x 到 7.2.0 的完整演进史。其中7.1.0 新增的 Kinesis / Kinesis FirehoseconfigureAutoTrack支持、7.2.0 的 AmplifyContext 优先调用形态与7.1.0 对 Pinpoint 默认导出的运行时弃用警告共同构成了当前版本最重要的三条迁移主线官方已宣布 Amazon Pinpoint 将于 2026 年 10 月 30 日停止支持因此本文围绕 CHANGELOG 中记录的这些变更结合 analytics 包源码为读者提供一份读得懂变更、用得对 API、迁得走代码的实战指南——读完你将掌握子路径导出、自动埋点参数与缓冲刷新机制、Context 优先 API 的使用与兼容性边界。一、为什么这份 CHANGELOG 值得逐条细读三条主线变更速览aws-amplify/analytics包当前版本为 7.2.0见 package.json。CHANGELOG 从 2018 年的0.1.1-unstable.0一路记录到 7.2.0但真正影响日常开发的是顶部三个版本它们分别对应三条迁移主线版本变更类型核心内容7.2.0Minor全类别引入 AmplifyContext 优先重载fn(ctx, input)新增createAmplifyContext工厂、InvalidAmplifyContextError/NoAmplifyContextError类型化错误、SSR 请求级上下文隔离7.1.0MinorKinesis 与 Kinesis Firehose Provider 新增configureAutoTrack自动埋点支持7.1.0Patch默认PinpointAnalytics 导出开始发出一次性运行时弃用警告指向子路径导出7.0.94 → 7.0.91PatchAWS SDK v3 依赖升级bump 至^3.1012.0修复 smithy/config-resolver 解析文章以下部分将逐一展开先是配置形态与导入方式子路径导出、pinpoint 弃用、peer 依赖约束再是Provider 实现细节Kinesis 缓冲、configureAutoTrack、EventBuffer 源码最后是Context 优先 API 与兼容性7.2.0 的重载形态、资源深冻结、SSR 隔离并给出升级清单与迁移步骤。二、从 Pinpoint 默认导出到子路径导出导入方式的迁移2.1 为什么默认导出被标记为弃用CHANGELOG 7.1.0 Patch 条目明确记录The default (Amazon Pinpoint) Analytics APIs (record,identifyUser,configureAutoTrack,flushEvents) now emit a one-timeConsoleLoggerdeprecation warning at runtime, pointing customers to the supported sub-path exports. AWS ends support for Amazon Pinpoint on October 30, 2026.也就是说AWS 官方已宣布将于2026 年 10 月 30 日结束对 Amazon Pinpoint 的支持因此aws-amplify/analytics的默认PinpointAPI 进入弃用期。此次变更非破坏性类型与函数签名完全保留只是运行时打印一次警告。2.2 源码证据默认入口如何包装 Pinpoint API在 src/index.ts 中可以看到默认入口故意把 Pinpoint 的四个 API 包装后重新导出为默认 Analytics 表面import { configureAutoTrack as configureAutoTrackPinpoint, flushEvents as flushEventsPinpoint, identifyUser as identifyUserPinpoint, record as recordPinpoint, } from ./providers/pinpoint; import { deprecatePinpoint } from ./utils; export const record deprecatePinpoint(recordPinpoint); export const identifyUser deprecatePinpoint(identifyUserPinpoint); export const configureAutoTrack deprecatePinpoint(configureAutoTrackPinpoint); export const flushEvents deprecatePinpoint(flushEventsPinpoint);其中deprecatePinpointutils/deprecatePinpoint.ts是一个一次性警告包装器首次调用时通过ConsoleLogger打印弃用信息之后所有调用直接透传底层实现不会刷屏同时它被类型化为原函数完整类型TFn因此多签名重载如fn(input)与fn(ctx, input)在包装后依然完整暴露。2.3 正确的新导入方式四个子路径导出从aws-amplify主包而非aws-amplify/analytics内部包按 Provider 子路径导入是官方推荐的迁移目标。CHANGELOG 与源码 package.json 的exports字段共同印证了以下四个子路径import { record, configureAutoTrack, flushEvents } from aws-amplify/analytics/kinesis; import { record, configureAutoTrack, flushEvents } from aws-amplify/analytics/kinesis-firehose; import { record, flushEvents } from aws-amplify/analytics/personalize;子路径支持的 API对应 Provider 源码目录aws-amplify/analytics/kinesisrecord/configureAutoTrack/flushEventsproviders/kinesisaws-amplify/analytics/kinesis-firehoserecord/configureAutoTrack/flushEventsproviders/kinesis-firehoseaws-amplify/analytics/personalizerecord/flushEventsproviders/personalize注意personalize子路径不提供configureAutoTrack与identifyUser其目录下只有record.ts与flushEvents.ts两个 API 文件见 providers/personalize/apis。迁移时需按目标服务能力选择。此外即便不做代码迁移CHANGELOG 也提醒旧代码继续从默认入口导入 Pinpoint API 在 7.x 内依然可用只是会在运行时收到一次性警告——这给了充足的迁移缓冲期。2.4 版本约束peer 依赖与同一发布线原则CHANGELOG 7.2.0 明确列出了兼容性约束各类别包的aws-amplify/corepeer 最低版本提升至^6.19.0aws-amplify对aws-amplify/adapter-nextjs的 peer 最低版本提升至^6.21.0。并特别说明该保护仅在依赖树被重新解析时生效已有的 lockfile、npm ci、使用--legacy-peer-deps的安装、以及 yarn classic 仅警告不报错的 peer 依赖不会被重新检查。因此混合版本安装例如旧的aws-amplify/auth≤ 6.x 固定到core ^6.16.2却搭配新的 core仍可能发生且不受支持——务必让直接安装的aws-amplify/*类别包与aws-amplify保持在同一发布线。三、Kinesis Provider 深度解析record、flushEvents 与 configureAutoTrack3.1 record缓冲 定时批量上报Kinesis 的recordproviders/kinesis/apis/record.ts不会把事件立刻发往服务端而是写入一个全局事件缓冲器export function record(input: RecordInput): void { const [ctx, input] resolveCtxArgs[RecordInput](args); const { streamName, partitionKey, data } input; if (!isAnalyticsEnabled()) { logger.debug(Analytics is disabled, event will not be recorded.); return; } const timestamp Date.now(); const { region, bufferSize, flushSize, flushInterval, resendLimit } resolveConfig(ctx); resolveCredentials(ctx).then(({ credentials, identityId }) { const buffer getEventBuffer({ region, bufferSize, flushSize, flushInterval, credentials, identityId, resendLimit, userAgentValue }); buffer.append({ region, streamName, partitionKey, event: ArrayBuffer.isView(data) ? data : fromUtf8(JSON.stringify(data)), timestamp, retryCount: 0 }); }); }要点data既可以是ArrayBuffer视图如Uint8Array也可以是普通对象——后者会被fromUtf8(JSON.stringify(data))序列化后发送事件先入缓冲由EventBuffer按flushInterval定时批量发送flushSize条凭据credentials与 identityId 通过resolveCredentials异步解析。3.2 flushEvents主动冲刷缓冲flushEventsproviders/kinesis/apis/flushEvents.ts触发一次尽力而为的全面冲刷获取缓冲器后调用flushAll()将当前缓冲中的所有事件全部提交。CHANGELOG 源码注释同时提醒调用后紧接着新记录的事件不一定被包含在本次冲刷内。3.3 configureAutoTrack7.1.0 的核心新增能力7.1.0 之前configureAutoTrack仅 Pinpoint Provider 支持7.1.0PR #14854将其扩展到 Kinesis 与 Kinesis Firehose。看 providers/kinesis/apis/configureAutoTrack.tsexport function configureAutoTrack(ctx: AmplifyContext, input: KinesisConfigureAutoTrackInput): void; export function configureAutoTrack(input: KinesisConfigureAutoTrackInput): void; export function configureAutoTrack(...args: any[]): void { const { ctx, input } peekCtxArgsKinesisConfigureAutoTrackInput(args); validateTrackerConfiguration(input); if (input.enable) { assertValidationError(!!input.options?.streamName, AnalyticsValidationErrorCode.NoStreamName); assertValidationError(!!input.options?.partitionKey, AnalyticsValidationErrorCode.NoPartitionKey); } const emitTrackingEvent (eventName, attributes) { const recordInput { streamName: input.options!.streamName, partitionKey: input.options!.partitionKey, data: { name: eventName, attributes }, }; ctx ? record(ctx, recordInput) : record(recordInput); }; updateProviderTrackers(input, emitTrackingEvent, configuredTrackers, kinesis); }支持三种自动追踪器Tracker类型源码注释给出了完整示例type: event—— DOM 元素事件点击等type: session—— 会话事件type: pageView—— 页面浏览事件支持appType: singlePage单页应用模式。启用追踪时必须提供streamName与partitionKey否则抛出AnalyticsValidationErrorCode.NoStreamName/NoPartitionKey校验错误。自动追踪事件的上报数据负载形状固定为{ name: eventName, attributes }。React Native 平台目前仅支持 session 追踪。每个 Provider 的追踪器状态相互隔离以kinesis命名空间隔离避免与 Pinpoint 的 pageView 状态串扰。3.4 缓冲器源码EventBuffer 与默认配置utils/eventBuffer/EventBuffer.ts 实现了核心缓冲逻辑append()当缓冲长度超过bufferSize时丢弃新事件并打 debug 日志定时器按flushInterval周期性调用submitEvents(flushSize)取队头flushSize条批量提交submitEvents返回未成功的部分时通过insertAtBeginning放回队首重试flushAll()一次提交全部剩余事件。Kinesis Provider 的默认配置定义在 providers/kinesis/utils/constants.tsexport const DEFAULT_KINESIS_CONFIG { bufferSize: 1_000, // 缓冲上限 1000 条 flushSize: 100, // 每次批量发送 100 条 flushInterval: 5_000, // 每 5 秒冲刷一次 resendLimit: 5, // 最大重试次数 };resolveConfigproviders/kinesis/utils/resolveConfig.ts会从ctx.resourcesConfig.Analytics?.Kinesis读取覆盖配置与默认值合并后校验region必填否则抛NoRegion且要求flushSize bufferSize否则抛InvalidFlushSize。这些配置在Amplify.configure()的 resourcesConfig 中声明Amplify.configure({ Analytics: { Kinesis: { region: us-east-1, streamName: myKinesisStream, // record 时可省略但 configureAutoTrack 必填 partitionKey: myPartitionKey, // configureAutoTrack 必填 bufferSize: 1000, flushSize: 100, flushInterval: 5000, resendLimit: 5, }, }, });四、7.2.0 的 AmplifyContext 优先 API 与兼容性边界4.1 Context 优先重载fn(ctx, input)与单例形态并存CHANGELOG 7.2.0 的核心是跨所有类别的显式 AmplifyContext 支持PR #14931Adds context-first overloads (fn(ctx, input)) to category APIs alongside the existing singleton-based forms, a publiccreateAmplifyContext(resourcesConfig, libraryOptions?)factory for isolated per-request/per-tenant contexts, per-request context isolation inaws-amplify/adapter-nextjsSSR, typed misuse errors (InvalidAmplifyContextError,NoAmplifyContextError), and a shared testing entry (aws-amplify/core/internals/testing).这意味着每个类别 API 现在有两种调用形态// 单例形态沿用旧代码全局配置 record({ streamName, partitionKey, data }); // Context 优先形态新增显式隔离 const ctx createAmplifyContext(resourcesConfig, libraryOptions); record(ctx, { streamName, partitionKey, data });从 configureAutoTrack.ts 与 record.ts 的源码可以看到两个重载签名并存运行时通过peekCtxArgs/resolveCtxArgs判别是否传入显式 context。注意peekCtxArgs的特殊设计它不会回退到全局上下文从而避免在Amplify.configure()之前配置追踪器时抛错也让自动埋点事件在使用record时按发射时刻的实时配置而非设置时刻的快照来解析全局上下文。4.2 与既有 SSR 代码的向后兼容CHANGELOG 明确承诺向后兼容Backward compatible: existing application code — including pre-context SSRoperation: (contextSpec) fetchAuthSession(contextSpec)— compiles and behaves unchanged via deprecated type aliases.旧代码包括 SSR 中operation: (contextSpec) ...的写法继续编译、行为不变被弃用的AmplifyServer类型别名Context、ContextSpec、ContextToken、RunOperationWithContext以及函数式 shimcreateAmplifyServerContext/getAmplifyServerContext/destroyAmplifyServerContext在 internals/adapter-core 入口被恢复保证已发布版本的aws-amplify/adapter-nextjs仍能工作这些别名与 shim 将在下一个大版本移除。4.3 深冻结嵌套配置不可再变更7.2.0 还收紧了一处行为Resources config is now deep-frozen afterAmplify.configure()andcreateAmplifyContext()(previously frozen only at the top level). Code that mutated a nested config field post-configure — always unsupported — now throws in strict mode instead of silently succeeding.即configure()/createAmplifyContext()之后配置对象由顶层冻结升级为深冻结。过去对嵌套配置字段的修改本就不受支持在严格模式下会静默成功现在则会直接抛错。若你的代码在configure()之后修改过Analytics.Kinesis.*之类的嵌套字段7.2.0 起必须移除这类操作。4.4 两个附带 Bug 修复与配套测试7.2.0 还包含两项 api-graphql 修复记录在同一 PR 中SSR 请求客户端现在会正确遵守客户端级选项此前被静默丢弃events 的错误消息现在能准确描述失败原因。仓库中配套的单测可佐证以上行为例如 configureAutoTrack.test.ts 与 record.test.ts。五、历史版本中的工程演化要点对升级有实际意义除最近三个版本外CHANGELOG 中值得留意的工程性变更包括6.0.02022-11-09扩展*导出以优化 tree-shaking、移除大部分默认导出、启用 tslib/importHelpers 改善包体积、引入 TypeScript 覆盖率报告机制并修复了无 Auth 模块时的 guest 凭据问题、统一cache具名导出以兼容 React Native。5.2.02022-02-28Analytics TypeScript 类型更新。5.1.02021-10-07Web 端 Analytics 默认使用 PUSH channel 类型为缓存的 Pinpoint endpoint id 更新 TTL。4.0.02020-11-20破坏性变更——updateEndpoint不再自动删除旧 endpoint。升级到 4.x 及以上时需要注意此行为差异。3.1.02020-03-31core 类别迁移至 AWS SDK V3并给所有 V3 SDK 调用附加 Amplify user agent。2.2.02019-12-03新增AWS Kinesis FirehoseProvideraddAnalyticsProvider时代并支持批量发送事件。1.2.x 早期Pinpoint endpoint id 生成/缓存、session start/stop 事件、beforeunload 冲刷、自动 session 追踪等基础机制在此时期定型。对于从旧版本尤其是 5.x 及更早升级的读者需要特别核对旧 API 名与新子路径导出的对应关系、updateEndpoint行为变化4.0.0、以及所有 V3 化之后依赖的aws-sdk/*版本7.0.94 起为^3.1012.0。六、迁移实操从默认导出切到 Kinesis 的完整清单6.1 步骤一检查当前使用面在代码中搜索以下默认入口导入它们是 7.1.0 后会被警告、且面向 Pinpoint 停服必须迁走的 APIimport { record, identifyUser, configureAutoTrack, flushEvents } from aws-amplify; // 旧写法同时检查是否在Amplify.configure()之后修改过嵌套配置7.2.0 深冻结会抛错。6.2 步骤二按目标服务改写导入与配置以迁移到 Kinesis 为例import { Amplify } from aws-amplify; import { record, configureAutoTrack, flushEvents } from aws-amplify/analytics/kinesis; Amplify.configure({ Analytics: { Kinesis: { region: us-east-1, bufferSize: 1000, flushSize: 100, flushInterval: 5000, resendLimit: 5 }, }, }); // 埋点 record({ streamName: myKinesisStream, partitionKey: myPartitionKey, data: { name: click, attributes: { page: /home } } }); // 自动埋点页面浏览 configureAutoTrack({ enable: true, type: pageView, options: { streamName: myKinesisStream, partitionKey: myPartitionKey, appType: singlePage } }); // 主动冲刷 flushEvents();若要迁移到 Kinesis Firehose把导入路径换成aws-amplify/analytics/kinesis-firehose、配置字段改为Analytics.KinesisFirehose即可API 形态一致。6.3 步骤三验证与回归运行npm run test在仓库 analytics 包 目录下可看到record/flushEvents/configureAutoTrack/resolveConfig/EventBuffer等模块的 Jest 单测确认依赖版本满足 CHANGELOG 7.2.0 的约束aws-amplify/core≥ 6.19.0且所有直接安装的aws-amplify/*类别包与aws-amplify处于同一发布线若使用 SSR Next.js可结合 adapter-nextjs 的上下文 API 使用fn(ctx, input)形态实现按请求/按租户的隔离埋点。七、结语与延伸阅读本仓库的 packages/analytics/CHANGELOG.md 完整记录了一条从 Pinpoint 单 Provider 时代到多 Provider 子路径时代的技术路线。对当前开发者而言三条行动线最为关键① 7.1.0 起迁移默认导入到analytics/kinesis、analytics/kinesis-firehose、analytics/personalize子路径② 按需使用 Kinesis/Kinesis Firehose 的configureAutoTrack自动埋点并注意 streamName/partitionKey 必填与 React Native 仅支持 session③ 升级到 7.2.0 时改用fn(ctx, input)的 Context 优先形态以获得请求级隔离同时留意配置深冻结与AmplifyServer别名将在下个大版本移除。需要继续深入源码时建议阅读 src/providers/kinesis含 record.ts、configureAutoTrack.ts、resolveConfig.ts、src/utils/eventBuffer/EventBuffer.ts以及配套的tests目录。赞分享前端后端移动开发【免费下载链接】amplify-jsA declarative JavaScript library for application development using cloud services.项目地址https://gitcode.com/gh_mirrors/am/amplify-js点击查看免费下载相关推荐终极三星固件下载工具samloader无需Windows驱动的完整指南终极三星固件下载工具samloader无需Windows驱动的完整指南 samloader是一款专为三星设备设计的固件下载工具它让用户能够直接从官方服务器获开发工具CLIApache Druid Firehose 迁移指南从 firehose 到 input source 的完整实践Apache Druid Firehose 迁移指南从 firehose 到 input source 的完整实践 Apache Druid 自 0.17 起数据库OLAP大数据后端SkyWalking 监控 AWS DynamoDB基于 Kinesis Data Firehose 与 MAL 的指标接入实践SkyWalking 监控 AWS DynamoDB基于 Kinesis Data Firehose 与 MAL 的指标接入实践 Amazon DynamoD可观测性APM链路追踪指标监控日志分析微服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考