Keystone float 字段完整指南：配置、校验与 GraphQL 实战

后端【免费下载链接】keystoneThe superpowered headless CMS for Node.js — built with GraphQL and React项目地址https://gitcode.com/gh_mirrors/key/keystone点击查看免费下载float是 Keystone 中最常用的数值字段类型之一用于表示单精度浮点数floating point value可覆盖价格、评分、坐标、权重等一切需要小数的业务场景。本文以官方字段参考文档为主体结合本仓库keystone-6/core的真实源码与测试用例系统讲解 float 字段的全部配置选项、底层实现原理、Admin UI 交互行为及 GraphQL 查询过滤能力读完即可在生产项目中正确、完整地使用该字段。float 字段是什么在 fields/overview 的字段体系中float属于标量scalar字段类型它映射到 GraphQL 的Float标量在数据库层面对应各关系型数据库的浮点列PostgreSQL 的double precision、MySQL 的double、SQLite 的REAL在 Admin UI 中渲染为数值输入框。与 integer仅整数和 decimal高精度十进制不同float 适合精度要求不高、但需要小数的场景。从 实现源码 可以看到它通过fieldType({ kind: scalar, scalar: Float, ... })声明为 Float 标量。从 测试夹具 可以看到它的典型取值形态-21.5、0、1.2、2.3、3以及null都是合法值且supportsNullInput true、supportsUnique true、supportsDbMap true说明它原生支持空值、唯一索引和数据库列名映射。全部配置选项详解float 字段的完整配置项在源码的FloatFieldConfig类型中定义见 packages/core/src/fields/types/float/index.ts#L14-L30下面逐一说明。defaultValue创建时的默认值类型number | null默认undefined作用创建条目时若未显式传值则使用该值填充字段约束必须是有限浮点数finite float不能是Infinity或NaN源码在 packages/core/src/fields/types/float/index.ts#L41-L45 处做了严格校验如果默认值不是有限数字会直接抛出must be a valid finite number的配置错误并把错误定位到具体的listKey.fieldKey方便快速排查。db.map数据库列名映射类型string默认undefined作用为字段添加 Prismamap属性改变数据库中的列名适用场景列名与字段名不一致时使用例如字段名someFieldName、数据库列名my_float该选项透传给 Prisma schema 生成逻辑实现在 packages/core/src/fields/types/float/index.ts#L91 的map: config.db?.map。它只影响数据库列名不影响 GraphQL API 与代码中的字段名。db.isNullable数据库层是否允许为空类型boolean默认validation.isRequired ? false : true作用设为false时字段在数据库层变为非空NOT NULL永远不可能被设置为nullvalidation.isRequired必填校验类型boolean默认false作用设为true时字段不可为null在通过 GraphQL API 或 Admin UI 创建、更新条目时都会进行校验同时会把db.isNullable的默认值改为false空值判定逻辑见 packages/core/src/fields/non-null-graphql.ts#L50-L64创建时值为undefined、或创建/更新时值为null都会触发missing value校验错误。validation.min / validation.max数值范围校验类型number默认undefined作用min限制最小值、max限制最大值提交超出范围的值会得到校验错误源码中的实现非常清晰packages/core/src/fields/types/float/index.ts#L46-L60min、max同样必须是有限数字否则抛出配置错误若min max直接抛出has no valid options的配置错误从源头避免永远无法通过校验的死配置。运行时校验packages/core/src/fields/types/float/index.ts#L67-L80在创建和更新操作时执行删除操作跳过小于min报value must be greater than or equal to ${min}大于max报value must be less than or equal to ${max}。isIndexed数据库索引类型boolean | unique默认false作用true字段被数据库索引加速查询unique字段加唯一索引所有值必须唯一源码中索引声明见 packages/core/src/fields/types/float/index.ts#L88当设置为unique时还会在 GraphQL 层额外生成uniqueWhere查询参数第 101 行可通过唯一值直接定位条目。graphql.read.isNonNull读取输出非空类型boolean默认false作用当没有读取访问控制且未来也不打算添加时可设为true让 GraphQL 输出字段变为非空注意仅在没有读取访问控制时允许。原因在官方文档中有明确警告当存在访问控制且访问被拒绝时字段会返回null而非空字段返回null会触发错误并向上传播直到遇到可空字段这会导致整个条目不可读做items查询时所有条目都不可读源码对此有强制约束packages/core/src/fields/non-null-graphql.ts#L78-L99若未设置validation.isRequired: true或db.isNullable: false却设置graphql.isNonNull.read: true会直接抛出配置错误。graphql.create.isNonNull创建输入非空类型boolean默认false作用当没有创建访问控制时可设为true让 GraphQL 创建输入字段变为非空并在 GraphQL 层提供默认值注意仅在没有创建访问控制时允许。否则无论用户是否在 create 中指定该字段只要用户没有该字段的创建权限条目都会因访问控制而创建失败完整配置示例以下是官方文档中的完整示例组合了默认值、列名映射、必填校验与唯一索引import { config, list } from keystone-6/core; import { float } from keystone-6/core/fields; export default config({ lists: { SomeListName: list({ fields: { someFieldName: float({ defaultValue: 3.14159, db: { map: my_float }, validation: { isRequired: true, }, isIndexed: unique, }), /* ... */ }, }), /* ... */ }, /* ... */ });对上述配置逐项说明defaultValue: 3.14159在创建条目未传值时自动填充该数值同时它也会成为 GraphQL create 输入参数的默认值见源码 packages/core/src/fields/types/float/index.ts#L106-L115db.map将数据库列名改为my_floatvalidation.isRequired: true使字段必填并让db.isNullable默认变为false数据库列成为 NOT NULLisIndexed: unique生成唯一索引并额外开启uniqueWhere查询能力。更完整的配置形态可参考FloatFieldConfig类型定义packages/core/src/fields/types/float/index.ts#L14-L30它同时继承了CommonFieldConfig含label、ui、hooks、access、graphql等通用配置因此ui展示定制、hooks钩子、access权限控制等能力同样适用于 float 字段。GraphQL API查询、过滤、排序float 字段在 GraphQL 层的过滤类型由各数据库 provider 统一定义见 packages/core/src/fields/filters/providers/postgresql.ts#L213-L263SQLite、MySQL 中定义一致分别见 sqlite.ts 与 mysql.ts。当字段可空optional模式时生成的FloatNullableFilter与FloatFilter支持以下操作符操作符含义对应 Admin UI 筛选equals等于可传nullIs exactlynot不等于可嵌套对象Is not exactlyin/notIn在集合内 / 不在集合内—lt/lte小于 / 小于等于Is less than / less than or equal togt/gte大于 / 大于等于Is greater than / greater than or equal to当字段必填required模式时使用FloatFilter无null语义。字段还支持orderBy排序参数与可选的uniqueWhere唯一查询参数源码 packages/core/src/fields/types/float/index.ts#L100-L118。查询示例query { items(where: { someFieldName: { gte: 1.5, lt: 10 } }, orderBy: { someFieldName: asc }) { someFieldName } }Admin UI 中的交互行为float 字段在 Admin UI 中渲染为数值输入框实现见 packages/core/src/fields/types/float/views/index.tsx输入校验validate_ 函数必填时输入为空报${label} is required无法解析为数字报${label} is not a valid float超出min/max范围分别给出对应的范围错误提示提交序列化serialize输入先经parseFloat解析Number.isFinite判定为有限值才提交否则以null提交过滤面板Admin UI 列表页的过滤条件与 GraphQL 过滤一一对应TYPE_OPERATOR_MAP第 13-20 行将equals、not、gt、lt、gte、lte分别渲染为、≠、、、≥、≤另支持Is empty/Is not empty空值筛选字段元数据getAdminMeta将min、max与defaultValue传给 Admin UI 前端前端据此做即时校验并预填默认值。测试验证与边界行为float 字段的能力边界在仓库测试中有充分覆盖tests/api-tests/fields/types/float.test.ts 针对db.isNullable为true/false两种情况使用-21.5, 0, 1.2, 2.3, 3一组数值验证全部过滤操作符orderableFilterTests并对isIndexed: unique做唯一等值过滤测试uniqueEqualityFilterTest测试夹具 test-fixtures.ts 验证了负小数、零、小数、整数与null的存储往返一致性未显式赋值的条目post7读回为null非空夹具 non-null/test-fixtures.ts 验证了db.isNullable: false时所有条目必须提供有效数值、supportsGraphQLIsNonNull能力开启的行为。从源码结构还可以推断由于defaultValue同时作用于数据库默认值{ kind: literal, value }与 GraphQL create 输入默认值迁移生成的 Prisma schema 中会包含对应的默认值声明与map、unique等属性运行keystone prisma migrate dev即可同步到数据库。小结与选型建议float 字段的完整配置链路为字段配置index.ts→ 校验钩子non-null-graphql.ts 内联范围校验→ GraphQL 输入输出与过滤filters/providers→ Admin UI 控制器views/index.tsx。使用要点回顾精度敏感场景金额、税率等优先考虑 decimalfloat 适合评分、百分比、测量值等普通浮点场景必填与范围校验组合使用isRequiredmin/max前后端GraphQL 与 Admin UI会自动同步校验规则使用graphql.isNonNull.*前务必确认没有对应访问控制否则会导致条目整体不可读或创建失败需要按数值精确匹配、范围筛选或排序时float 自带的过滤操作符与orderBy已覆盖绝大多数需求。更多字段类型的横向对比与选型思路可继续阅读 fields/overview 及 integer、bigint 等相邻字段文档。赞分享后端【免费下载链接】keystoneThe superpowered headless CMS for Node.js — built with GraphQL and React项目地址https://gitcode.com/gh_mirrors/key/keystone点击查看免费下载相关推荐Keystone 6 密码字段password完整指南配置、校验、哈希与 GraphQL 行为Keystone 6 密码字段password完整指南配置、校验、哈希与 GraphQL 行为 本文以 Keystone 6 官方字段参考文档 docs/后端Keystone 6 Multiselect 字段完整指南类型、选项与 GraphQL 集成实战Keystone 6 Multiselect 字段完整指南类型、选项与 GraphQL 集成实战 导读 multiselect 是 Keystone 内置的“后端douyin-downloader 零基础教程30分钟跑通第一次抖音无水印批量下载douyin downloader 零基础教程30分钟跑通第一次抖音无水印批量下载 想把某位博主的作品存下来手动一个个点保存又慢又乱存进相册还带着水印d网页爬虫CLI上一篇c-ares 单元测试套件全解析构建、运行、源码级测试架构与覆盖率实践fluent-bit 内嵌 c-ares 1.34.6下一篇3步开启离线语音转文字Buzz让你的音频文件秒变文字稿创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考