Keystone 整数（integer）字段完全指南：32 位有符号整数的配置、校验与最佳实践

后端【免费下载链接】keystoneThe superpowered headless CMS for Node.js — built with GraphQL and React项目地址https://gitcode.com/gh_mirrors/key/keystone点击查看免费下载integer是 Keystone 内置的基础字段类型用于在内容模型中存储 32 位有符号整数对应 GraphQL 的Int标量。本文以 Keystone 官方文档中关于integer字段的参考说明为主体结合keystone-6/core仓库中的字段核心实现、Admin UI 视图组件与测试用例逐项讲解defaultValue、db.isNullable、db.map、validation、isIndexed、graphql.isNonNull等全部配置项的语义与底层原理。读完本文你将能够根据业务需求唯一排序号、自增计数、严格数值范围校验等正确配置integer字段并理解它在数据库、GraphQL API 与 Admin UI 三层的完整行为。integer 字段是什么在 Keystone 的字段体系中integer字段表示一个32 位有符号整数signed 32-bit integer取值范围为-2147483648-2^31到21474836472^31 - 1。超出该范围的值在数据库与 API 层面都会产生错误这一点在实现层面由字段的Int标量类型强制约束。从源码结构看该字段在 packages/core/src/fields/types/integer/index.ts 中定义其类型配置IntegerFieldConfig继承了CommonFieldConfig并声明底层标量为SimpleFieldTypeInfoInt。也就是说integer字段在 GraphQL 中暴露为Int标量在 Prisma Schema 中映射为整数列在 Admin UI 中则渲染为数字输入框基于 Keystar UI 的NumberField。最小配置与完整配置示例在列表list的fields中通过integer函数声明一个整数字段无需任何参数即可使用import { config, list } from keystone-6/core; import { integer } from keystone-6/core/fields; export default config({ lists: { SomeListName: list({ fields: { /* 最简单的用法无任何配置 */ plainInteger: integer(), /* 完整配置同时使用默认值、数据库列名映射、必填校验与唯一索引 */ someFieldName: integer({ defaultValue: 0, db: { map: my_integer }, validation: { isRequired: true, }, isIndexed: unique, }), /* ... */ }, }), /* ... */ }, /* ... */ });上例同时演示了四种常用能力defaultValue为新纪录提供默认值db.map修改数据库列名validation.isRequired强制该字段在创建与更新时不可为空isIndexed: unique为字段建立唯一索引。仓库中的 examples/number-fields/schema.ts 也提供了integer()与integer({ defaultValue: 789 })的实战示例可供直接参考。配置项逐项详解integer字段支持的全部配置项如下每个选项的语义与底层行为我们逐一展开。defaultValue默认值类型整数、null、或{ kind: autoincrement }默认值undefined无默认值defaultValue指定创建新条目时若未显式提供该字段值所用的默认值。{ kind: autoincrement }表示自动递增仅在 PostgreSQL 数据库上受支持MySQL 与 SQLite 不适用仓库示例 examples/number-fields/schema.ts 中即以注释形式标注了这一点“WARNING: not supported by SQLite”。在实现层面integer/index.ts配置会先被规范化const defaultValue typeof defaultValue_ number ? defaultValue_ : (defaultValue_?.kind ?? null);随后在fieldType的default属性中映射为两种数据库默认值形式integer/index.ts数值型默认值 →{ kind: literal, value: defaultValue }数据库字面量默认值autoincrement→{ kind: autoincrement }数据库自增由 Prisma 生成default(autoincrement())。需要特别注意的是当使用{ kind: autoincrement }时字段在 Admin UI 中会被置为只读并显示 “Auto increment” 提示“This field is set to auto increment. It will default to the next available number.”这一行为由视图层 views/index.tsx 中的isReadOnly !onChange || field.hasAutoIncrementDefault逻辑控制。db.isNullable数据库层是否允许为空类型boolean默认值validation.isRequired ? false : truedb.isNullable控制数据库列的 null 约束。为false时数据库列被定义为 NOT NULL字段永远不可能被置为null。其解析逻辑位于 packages/core/src/fields/non-null-graphql.ts 的resolveDbNullableexport function resolveDbNullable( validation: undefined | { isRequired?: boolean }, db: undefined | { isNullable?: boolean } ): boolean { if (db?.isNullable false) return false if (db?.isNullable undefined validation?.isRequired) { return false } return true }可见显式声明db.isNullable: false的优先级最高未显式声明时若validation.isRequired为true也会推导为非空。最终isNullable决定字段 GraphQL 模式的modeoptional或required并影响对应的过滤器类型选择见下文“过滤与排序”一节。db.map数据库列名映射类型stringdb.map为字段添加 Prisma 的map属性从而改变字段在数据库中的实际列名。例如db: { map: my_integer }会把该字段对应的数据库列命名为my_integer而 GraphQL 与 Admin UI 中仍使用字段名someFieldName。这在对接既有数据库表、避免列名与数据库关键字冲突时非常实用。在 integer/index.ts 中map: config.db?.map被直接透传给fieldType最终体现在生成的 Prisma Schema 字段上。validation.isRequired必填校验类型boolean默认值falsevalidation.isRequired为true时该字段永远不能被设置为null并且会在通过GraphQL API 或 Admin UI创建、更新条目时执行校验。同时如上面resolveDbNullable所示它还会把db.isNullable的默认值推导为false。底层实现non-null-graphql.ts会生成一个validate钩子当字段值在 create 时缺失、或在 create/update 时为null会调用addValidationError(missing value)阻止写入。validation.min / validation.max数值范围校验类型number必须是整数默认值min为-2147483648max为2147483647validation.min与validation.max描述允许提交的最小值与最大值。提交超出范围的数字会触发校验错误“value must be greater than or equal to X” / “value must be less than or equal to X”。若希望把数字限定在某个区间内需要同时指定 min 与 max。这两个默认值即 32 位有符号整数的边界在实现中定义为常量integer/index.ts// for a signed 32-bit integer const MAX_INT 0x7fffffff const MIN_INT -0x80000000更值得关注的是启动期配置校验integer/index.tsKeystone 在初始化列表时会直接抛出错误拒绝启动而不是等到运行时才暴露问题defaultValue不是整数 → 报错min/max不是整数 → 报错min或max超出 32 位有符号整数范围 0x7fffffff或 -0x80000000→ 报错min max区间内无任何合法值→ 报错并提示 “has no valid options”。这些错误消息中带有${meta.listKey}.${meta.fieldKey}方便快速定位是哪个列表的哪个字段配置有误。而在 Admin UI 端视图控制器同样会基于validation.min/validation.max做前端即时校验views/index.tsx。isIndexed索引与唯一约束类型boolean | unique默认值falseisIndexed控制数据库索引true→ 数据库为该列创建普通索引unique→ 该字段的所有值必须唯一数据库创建唯一索引同时 GraphQL 会生成uniqueWhere查询参数用于按该字段查找单条记录。实现中integer/index.tsindex: isIndexed true ? index : isIndexed || undefined负责把配置映射为fieldType的索引声明而isIndexed unique时还会生成uniqueWhere输入参数integer/index.ts。graphql.read.isNonNull读取输出非空类型boolean默认值falsegraphql.read.isNonNull使 GraphQL 输出字段变为非空non-nullable。它仅在没有任何读取访问控制read access control时允许开启因为一旦存在读取访问控制当访问被拒绝时字段会返回null——此时若字段声明为非空错误会沿类型系统向上传播直到遇到可空字段为止最终导致整个条目甚至items查询的全部条目都无法读取。此外实现层还有一条硬性约束non-null-graphql.ts 的assertReadIsNonNullAllowed设置graphql.isNonNull.read: true时必须同时设置validation.isRequired: true或db.isNullable: false否则 Keystone 启动时会抛出明确错误提示。graphql.create.isNonNull创建输入非空类型boolean默认值falsegraphql.create.isNonNull使创建create输入中的该字段变为非空并在 GraphQL 层面对其应用默认值即 create 输入字段带上defaultValue。它仅在没有任何创建访问控制时允许开启否则只要某个用户没有该字段的创建权限无论他在 create 时是否显式提交该字段条目都会因无法通过访问控制而创建失败。在实现中integer/index.tscreate 输入参数arg: g.arg({ type: g.Int, defaultValue: ... })会根据是否配置了数值型默认值来决定是否在 GraphQL 层注入默认值。数据库与 Prisma 层的行为integer字段在数据库层最终体现为整数列。以下典型 Prisma 声明可以帮助你理解配置如何落到 Schema 上实际 Schema 由 Keystone 自动生成无需手写model SomeListName { id Int id default(autoincrement()) someFieldName Int? map(my_integer) // db.map 改变列名 plainInteger Int? // 默认可空 // 若 validation.isRequired: true 或 db.isNullable: false // someFieldName Int map(my_integer) // 若 defaultValue: 0 // plainInteger Int default(0) // 若 defaultValue: { kind: autoincrement }仅 PostgreSQL // someFieldName Int default(autoincrement()) }值得一提的还有db.extendPrismaSchemaIntegerFieldConfig的db对象额外支持extendPrismaSchema?: (field: string) string回调integer/index.ts允许你在生成的 Prisma 字段上追加自定义属性如db.Integer用于更细粒度的数据库类型控制。该字段映射到 Prisma 类型时默认会依据数据库方言选择IntPostgreSQL/MySQL等对应整数类型。GraphQL 层过滤、排序与输入integer字段在 GraphQL 层暴露为Int标量并自动获得完整的查询能力过滤where支持equals、not、gt、lt、gte、lte、empty、not_empty等过滤器。过滤器类型由各数据库方言的过滤器表决定例如 packages/core/src/fields/filters/providers/postgresql.tsexport const Int { optional: IntNullableFilter, required: IntFilter, }其中optional与required分别对应字段可空与不可空两种模式mysql.ts 与 sqlite.ts 中同样有对应的Int过滤器定义。排序orderBy通过orderBy参数按该字段升序asc或降序desc排序输入参数类型为orderDirectionEnum。唯一查询uniqueWhere当isIndexed: unique时生成可用于按该字段精确定位记录。上述能力均有对应测试覆盖tests/api-tests/fields/types/integer.test.ts 对db.isNullable为true/false两种模式分别执行了filterTests覆盖各过滤算子、orderableFilterTests覆盖排序以及uniqueEqualityFilterTest覆盖唯一等值查询测试数据包含负数与正数-234, 0, 5, 43, 65345确保整数比较、排序、空值语义在各模式下行为正确。Admin UI 层输入与过滤体验在 Admin UI 中integer字段的编辑器由 views/index.tsx 提供基于 Keystar UI 的NumberField渲染数字输入以step{1}强制整数步进并在提交时做Number.isInteger校验非整数会提示 “is not a valid integer”即时范围校验复用validation.min/validation.max超出范围即提示 “must be greater than or equal to X” / “must be less than or equal to X”必填提示validation.isRequired时输入为空会提示 “is required”自动递增字段只读defaultValue: { kind: autoincrement }时输入框置为只读并显示说明文本列表过滤字段过滤器 UI 提供 / ≠ / / / ≥ / ≤六种运算符对应equals、not、gt、lt、gte、lte见视图中的TYPE_OPERATOR_MAP外加 “Is empty / Is not empty” 空值过滤与 GraphQL 层where参数一一对应。实战要点小结需要 32 位以上数值时不要使用integer应改用bigInt字段examples/number-fields/schema.ts 中同时演示了bigInt、float与integer的用法对比。自增主键之外的业务自增号如订单号、排序号可在 PostgreSQL 上使用defaultValue: { kind: autoincrement }但需注意该字段在 Admin UI 中只读。自定义数值区间应同时设置validation.min与validation.max配置非法如min max或超出 32 位范围会在启动时被拦截。唯一业务键如 ISBN、库存编号使用isIndexed: unique可同时获得数据库唯一约束与 GraphQLuniqueWhere查询能力。开启graphql.isNonNull.*前务必确认没有对应的读取/创建访问控制否则会出现条目整体不可读或创建必然失败的隐患。如需查看更多字段类型的完整参考可以继续阅读 docs/content/docs/fields 目录下的其他文档字段的源码实现集中在 packages/core/src/fields 中是深入理解每个配置项底层行为的首选入口。赞分享后端【免费下载链接】keystoneThe superpowered headless CMS for Node.js — built with GraphQL and React项目地址https://gitcode.com/gh_mirrors/key/keystone点击查看免费下载相关推荐LeetCode-Go 题解 0008String to Integer (atoi)——Go 实现 32 位有符号整数字符串转换LeetCode Go 题解 0008String to Integer atoi ——Go 实现 32 位有符号整数字符串转换 导读 本篇基于 LeetCo示例工程Keystone float 字段完整指南配置、校验与 GraphQL 实战Keystone float 字段完整指南配置、校验与 GraphQL 实战 float 是 Keystone 中最常用的数值字段类型之一用于表示单精度浮点后端Keystone 6 密码字段password完整指南配置、校验、哈希与 GraphQL 行为Keystone 6 密码字段password完整指南配置、校验、哈希与 GraphQL 行为 本文以 Keystone 6 官方字段参考文档 docs/后端上一篇5分钟快速上手Blender完美支持3MF格式的终极指南下一篇5分钟快速上手让Blender完美支持3MF格式的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考