@energica-city/shared-amplify-utils
TypeScript 工具 此平台的每个后端处理器都来自: 错误处理, 结构化 记录,类型安全数据库操作 与内存卡, 和Lambda中间软件链.
三个寄存器要靠这个 —— 说 Eve-Backend-v2, (中文(简体) ), cdk-test-proyect 财务报告和审定财务报表
eve_adminwebv3。 。 。 . energica_payments 没有。 这里的变化在三个地方达到生产,所以
它是工作空间中最高的杠杆存储器 也是最容易破解遥远事物的
从.
安装
npm install @energica-city/shared-amplify-utils
⚠ 一切从包根入出. package.json 宣布单项 "." 导出,所以
子路径导入不能解决:
import { logger, throwError, QueryFactory } from "@energica-city/shared-amplify-utils"; // ✅
import { logger } from "@energica-city/shared-amplify-utils/log"; // ❌ no such export
标题 源目录 一个工具存在,而不是导入路径.
发展中国家
来源位于寄存器根部,而非下 src/。 。 。 .
npm install
npm run build # tsc → dist/
npm test # vitest, once
npm run test:watch # watching
npm run lint && npm run format:check
npm run gate # the repo's whole gate — what the pre-commit hook runs
npm run fix # prettier --write, then eslint --fix
npm run build:verify # = npm run build; what the pre-push hook runs
工作空间大门../tools/run-all-tests.sh shared运行雷波 gate 脚本: 类型检查,
提示、格式和测试一起通过.
出版
npm run release:patch # a fix that changes no behaviour
npm run release:minor # anything a consumer must act on — see CHANGELOG.md
npm run release:major
每个释放状态 CHANGELOG.md 消费者必须改变什么才能接受.
prepublishOnly 构建、测试、用意和格式检查先行完成,所以在发布失败之前
离开机器。 出版为a 与推动分开的一步 与五人中的三人不同
这里的仓库, git push 没有船.
⚠ 出版只是工作的一半. 三个消费者 ^ 范围,所以新版本到达
只有当他们 package.json 予以更新并重新部署。 跳出这个图书馆意味着
更新所有三个并说.
模块
错误—— error/
以结构化记录和上下文保存为标准的错误处理.
核心职能:
throwError(message, context)- 采用结构化上下文和自动伐木extractErrorMessage(error)- 从任何错误类型中提取一致的信息createErrorContext(data)- 创建过滤上下文对象
WebSocket 错误 :
throwWebSocketError(statusCode, code, message, context)- 特定WebSocket错误isWebSocketError(error)- WebSocket 错误的护卫类型WebSocketErrorCodes- 预定义错误代码(评估错误、自动错误等)
import { throwError, createErrorContext } from "@energica-city/shared-amplify-utils";
throwError("Operation failed", createErrorContext({ userId: "123", operation: "create" }));
伐木 - log/
一个 logger API 有两台引擎,由软件包选择 exports 条件:
- 节点 (兰布达) ——AWS兰巴达动力工具. 莲·杰森的台词:
timestamp, (中文(简体) ),level, (中文(简体) ),message, (中文(简体) ),requestId,跟踪键(buyOrder, (中文(简体) ),stationId, (中文(简体) ),eveId, (中文(简体) ),connectorId, (中文(简体) ),residenceId, (中文(简体) ),stage),然后是数据;每行最多16KB. - 浏览器 (单位:千美元)
browser条件)——控制台引擎:相同的API,相同的编辑,没有线索.
每个行是 已编辑: 邮件、电话、自动取款机和名称被遮盖;卡片、银行、信使、地址和 已编辑自由文本字段; 已擦除自由字符串 。 追踪键可以读取,它们就是一条线 已找到.
线索 保存细节——数据库读取,原始请求,GraphQL参数,只写它
当祈祷失败的时候, trail.flush()),或
当函数的级别是 DEBUG 时直接出现.
import { logger, trail, withInvocation, configureTrail } from "@energica-city/shared-amplify-utils";
configureTrail({ maxBytes: 256 * 1024 }); // once, at module load
export const handler = (event, context) =>
withInvocation(context, async () => {
logger.setContext({ buyOrder: event.buyOrder });
trail.info("charge read", { charge }); // only if this invocation fails
logger.info("charge settled", { amountUsedAccounting });
});
时空被杀死的蓝巴达没有 catch。 。 。 . configureInvocation 制造 withInvocation 调用 a
钩子在杀前不久,冲出小道后,所以回波可以引起一起事件:
import { configureInvocation } from "@energica-city/shared-amplify-utils";
configureInvocation({
timeoutMarginMs: 3000, // default
onTimeout: async ({ requestId, functionName, logGroup, remainingMs }) => {
await reportIncident({ requestId, functionName, logGroup, remainingMs });
},
}); // once, at module load; a later call replaces the settings
丢出或拒绝的钩被记录并吞入;浏览器中是禁用.
按名称或编号划分的级别 AWS_LAMBDA_LOG_LEVEL (函数的日志配置),然后
POWERTOOLS_LOG_LEVEL,则 LOG_LEVEL页:1.
查询厂 - queries/
CRUD用于扩展数据模型的型号安全操作,具有自动客户端管理,连接集成,以及可选择的与LRU拆迁相接的内膜缓存.
核心特征 :
- 类型安全数据库操作
- 自动客户端管理和连接集
- Schema 驱动的标识符提取
- 可选的默认读取缓存, 关闭,除非
enabled: true - 每一篇经文,都阐明其过时之处;
invalidate(id)用于其他作者 - 有条件写作(
condition, (中文(简体) ),authMode每个操作 - 短发相投, 除非
allowTruncation: true - 对复杂识别资料的综合关键支持
基本用途:
import { QueryFactory, initializeQueries } from "@energica-city/shared-amplify-utils";
await initializeQueries<MainTypes>(outputs);
const UserQueries = await QueryFactory<"User", MainTypes>({ name: "User" });
const user = await UserQueries.create({
input: { username: "john", email: "[email protected]" },
});
const foundUser = await UserQueries.get({ input: { userId: user.id } });
await UserQueries.update({ input: { userId: user.id, validated: true } });
await UserQueries.delete({ input: { userId: user.id } });
与缓冲:
const UserQueries = await QueryFactory<"User", MainTypes>({
name: "User",
cache: { enabled: true, ttl: 60_000 }, // off unless enabled: true
});
await UserQueries.get({ input: { userId: "123" } }); // database
await UserQueries.get({ input: { userId: "123" } }); // cache
await UserQueries.update({ input: { userId: "123", validated: true } }); // clears it
UserQueries.invalidate({ userId: "123" }); // after a write by anyone else
一个缓存住在一个温暖的Lambda容器里, 一个负责决定来自 a 读作——结算、退款、重复支票——不应缓存该模式.
作为Lambda自己的角色:
await initializeQueries({ amplifyOutputs, schema, credentials: "lambdaRole" }); // iam, signed as the role
中间软件 - middleware/
AWS Lambda 通用可相容中件链,有 REST, WebSocket, 和 GraphQL 支持.
核心中件链
import { MiddlewareChain } from "@energica-city/shared-amplify-utils";
const chain = new MiddlewareChain<MyInput, MyOutput>();
chain.use("auth", authMiddleware).use("validation", validationMiddleware);
const result = await chain.execute(input, finalHandler);
REST 中间软件
完成 AWS API Gateway 的 REST API 中间软件系统,并配备 HTTP 特定错误处理.
import {
createRestChain,
wrapRestHandler,
createRestErrorHandler,
createRestRequestLogger,
createRestRequestValidator,
createRestModelInitializer,
getValidatedBody,
getModelsFromInput,
} from "@energica-city/shared-amplify-utils";
const chain = createRestChain<MainTypes>()
.use("errorHandler", createRestErrorHandler())
.use("logger", createRestRequestLogger())
.use("modelInitializer", createRestModelInitializer({ entities: ["User"] }))
.use("validator", createRestRequestValidator({ bodySchema: userSchema }));
export const handler = wrapRestHandler(chain, async input => {
const { User } = getModelsFromInput(input);
const body = getValidatedBody(input);
return createSuccessResponse(await User.create({ input: body }));
});
WebSocket 中端软件
用于AWS API Gateway WebSocket API的WebSocket特有中间软件,具有实时连接管理功能.
import {
createWebSocketChain,
wrapWebSocketHandler,
createWebSocketErrorHandler,
createWebSocketModelInitializer,
getModelFromInput,
} from "@energica-city/shared-amplify-utils";
const chain = createWebSocketChain<MainTypes>()
.use("errorHandler", createWebSocketErrorHandler())
.use("modelInitializer", createWebSocketModelInitializer({ entities: ["Message"] }));
export const handler = wrapWebSocketHandler(chain, async input => {
const MessageModel = getModelFromInput(input, "Message");
// WebSocket handler logic
});
图形QL 中端软件
AWS AppSync 的 GraphQL 解析器中间软件,并带有可扩展的数据集成和结构化的错误处理.
import {
createGraphQLChain,
wrapGraphQLResolver,
createGraphQLErrorHandler,
createGraphQLRequestLogger,
createGraphQLModelInitializer,
getModelsFromInput,
extractArguments,
} from "@energica-city/shared-amplify-utils";
const chain = createGraphQLChain<MainTypes>()
.use("modelInitializer", createGraphQLModelInitializer({ entities: ["User", "Post"] }))
.use("logger", createGraphQLRequestLogger())
.use("errorHandler", createGraphQLErrorHandler());
export const handler = wrapGraphQLResolver(chain, async input => {
const { User } = getModelsFromInput(input);
const { userId } = extractArguments(input);
return await User.get({ input: { userId } });
});
验证 Utils
通用验证模式和数据消毒公用事业.
import { ValidationPatterns, sanitizeObject } from "@energica-city/shared-amplify-utils";
// Pre-built patterns
ValidationPatterns.uuid(); // UUID validation
ValidationPatterns.email(); // Email format validation
ValidationPatterns.pagination(); // Page/limit parameters
// Data sanitization
const clean = sanitizeObject(data, { excludeFields: ["secret"], maxDepth: 3 });
配置
环境变量:
AWS_LAMBDA_LOG_LEVEL编号 :POWERTOOLS_LOG_LEVEL编号 :LOG_LEVEL: 日志级别, 按名称或0–4EVE_TRAIL_MAX_BYTES: 如果configureTrail未调用STRUCTURED_LOGGING: 强制控制台引擎的 JSON 输出 ('ret'/'false')NODE_ENV数字 :development是显示堆栈和内部消息的唯一值
AWS Lambda 自动检测 :
- 节点条目通过Powertools来写;
withInvocation将请求id添加到每行 - 在启用时, 读取缓存会持续使用温和引用
所需资源
- 节点.js 20+
- 类型脚本 5.6+
- AWS 扩展 6.0+
- YP 1.6+ (用于审定)
- lu-cache 11.0+ (用于内膜缓冲)
出口
// Root exports only
export * from "./error";
export * from "./log";
export * from "./queries";
export * from "./middleware";
// All imports from root package
import { throwError } from "@energica-city/shared-amplify-utils";
import { logger } from "@energica-city/shared-amplify-utils";
import { QueryFactory, AppError } from "@energica-city/shared-amplify-utils";
一个 "." 导出,带有 browser 条件交换日志引擎; 没有子路径
出口.