⚡

添加字段到Bknd实体Skill bknd-add-field

此技能用于在Bknd后端框架中向现有实体添加新字段，涵盖文本、数字、布尔、日期、枚举、JSON、JSONSchema和媒体等多种字段类型，支持字段修饰符如.required()、.unique()、.default()，并提供UI和代码两种操作方法，包括验证选项和命名约定。关键词：Bknd、后端开发、数据库字段、添加字段、实体管理、字段验证、UI模式、代码模式、数据模型、API集成。

后端开发 0 次安装 0 次浏览 更新于 3/9/2026

name: bknd-add-field description: 当向现有Bknd实体添加字段时使用。覆盖所有字段类型（文本、数字、布尔、日期、枚举、json、jsonschema、媒体）、字段修饰符（.required()、.unique()、.default()）、验证选项和UI与代码方法。

添加字段到实体

在Bknd中向现有实体添加新字段（列）。

先决条件

  • 现有的Bknd实体（参见 bknd-create-entity）
  • 对于代码模式：访问您的模式文件

何时使用UI vs 代码

使用UI模式时

  • 快速迭代/原型设计
  • 非开发者添加字段
  • 在编码前测试字段配置

使用代码模式时

  • 需要版本控制
  • 可重现的模式更改
  • 需要类型安全
  • 团队协作

UI方法

步骤 1: 访问实体

  1. 启动服务器：npx bknd run
  2. 打开 http://localhost:1337
  3. 导航到 数据 部分
  4. 点击目标实体（例如 posts）

步骤 2: 添加字段

  1. 点击 + 添加字段
  2. 从下拉菜单中选择字段类型：
    • 文本：字符串、电子邮件、URL
    • 数字：整数、小数
    • 布尔：真/假
    • 日期：时间戳
    • 枚举：固定值集
    • JSON：非结构化数据
  3. 输入字段名称（蛇形命名：first_name、created_at）

步骤 3: 配置选项

根据字段类型配置：

所有类型：

  • 必需：如果字段不能为空，则切换开启
  • 默认值：设置默认值

文本：

  • 最小/最大长度
  • 模式（正则表达式验证）

数字：

  • 最小值/最大值
  • 倍数（针对整数）

枚举：

  • 添加枚举值（每行一个）

步骤 4: 保存和同步

  1. 点击 保存字段
  2. 点击 同步数据库 以应用更改

代码方法

步骤 1: 定位实体定义

在模式中找到您的实体：

const schema = em({
  posts: entity("posts", {
    title: text().required(),
    // 在此处添加新字段
  }),
});

步骤 2: 添加字段

将新字段添加到实体的字段对象中：

const schema = em({
  posts: entity("posts", {
    title: text().required(),
    subtitle: text(),           // 新增：可选文本字段
    view_count: number(),       // 新增：可选数字字段
  }),
});

步骤 3: 重启服务器

Bknd在启动时自动同步模式。重启服务器以应用更改。

字段类型参考

文本字段

import { text } from "bknd";

entity("users", {
  // 基本可选文本
  bio: text(),

  // 必需文本
  email: text().required(),

  // 唯一约束
  username: text().unique(),

  // 带验证
  slug: text({
    minLength: 3,
    maxLength: 100,
    pattern: "^[a-z0-9-]+$",
  }).required(),

  // 带默认值
  status: text({ default_value: "active" }),
})

数字字段

import { number } from "bknd";

entity("products", {
  // 基本数字
  quantity: number(),

  // 带验证的必需字段
  price: number({
    minimum: 0,
    maximum: 99999.99,
  }).required(),

  // 仅整数（multipleOf: 1）
  rating: number({
    minimum: 1,
    maximum: 5,
    multipleOf: 1,
  }),
})

布尔字段

import { boolean } from "bknd";

entity("posts", {
  // 默认为假
  published: boolean(),

  // 默认真
  active: boolean({ default_value: true }),
})

日期字段

import { date } from "bknd";

entity("events", {
  // 基本日期
  start_date: date().required(),

  // 自动设置为当前时间
  created_at: date({ default_value: "now" }),
})

枚举字段

注意： 导入为 enumm（双’m’）以避免JS保留字。

import { enumm } from "bknd";

entity("posts", {
  // 数组语法
  status: enumm({
    enum: ["draft", "published", "archived"],
    default_value: "draft",
  }).required(),

  // 对象语法（键值对）
  priority: enumm({
    enum: {
      LOW: "low",
      MEDIUM: "medium",
      HIGH: "high",
    },
    default_value: "MEDIUM",
  }),
})

JSON字段

import { json } from "bknd";

entity("users", {
  // 无类型JSON
  metadata: json(),

  // 类型化JSON（仅TypeScript，无运行时验证）
  preferences: json<{
    theme: "light" | "dark";
    notifications: boolean;
  }>(),

  // 带默认值
  tags: json<string[]>({ default_value: [] }),
})

JSON Schema字段

用于运行时验证的JSON：

import { jsonschema } from "bknd";

entity("webhooks", {
  payload: jsonschema({
    type: "object",
    properties: {
      event: { type: "string" },
      timestamp: { type: "number" },
    },
    required: ["event", "timestamp"],
  }),
})

媒体字段

用于文件附件：

import { media } from "bknd";

entity("posts", {
  // 单个文件
  cover_image: media({ entity: "posts" }),

  // 带约束的多个文件
  gallery: media({
    entity: "posts",
    min_items: 1,
    max_items: 10,
    mime_types: ["image/jpeg", "image/png", "image/webp"],
  }),
})

字段修饰符

在字段类型后链接修饰符：

修饰符 描述 示例
.required() 不能为空 text().required()
.unique() 唯一约束 text().unique()
.default(value) 默认值 text().default("pending")
.references(target) 外键 number().references("users.id")

链接示例：

entity("users", {
  email: text().required().unique(),
  role: text().default("user"),
  org_id: number().references("organizations.id"),
})

字段命名约定

约定 示例 注意
蛇形命名 first_name 非 firstName
小写 created_at 非 CreatedAt
描述性 published_at 非 pub

常见问题

字段已存在

错误： 字段 "title" 在实体 "posts" 上已存在

修复： 每个字段名称在实体中必须唯一。选择其他名称。

无效字段名称

错误： 无效字段名称

修复： 使用小写字母、数字和下划线。必须以字母开头。

// 有效
title: text()
first_name: text()
item_2: text()

// 无效
Title: text()        // 无大写
2_item: text()       // 不能以数字开头
first-name: text()   // 无连字符

枚举导入错误

错误： enum 是保留字

修复： 导入并使用 enumm（双’m’）：

// 错误
import { enum } from "bknd";

// 正确
import { enumm } from "bknd";

status: enumm({ enum: ["a", "b"] })

现有数据上缺少必需修饰符

问题： 在已有空值的字段上添加 .required()。

修复： 要么：

  1. 首先更新现有记录为非空值
  2. 添加默认值：text({ default_value: "N/A" }).required()
  3. 保持字段可选

字段更改未反映

问题： 在代码中添加字段但未出现。

修复：

  1. 重启服务器（模式在启动时同步）
  2. 验证字段在正确的实体定义中
  3. 检查模式中的语法错误

验证

UI模式

  1. 点击数据部分中的实体
  2. 验证新字段出现在字段列表中
  3. 使用新字段创建测试记录

代码模式

const api = app.getApi();

// 使用新字段创建记录
const result = await api.data.createOne("posts", {
  title: "测试",
  subtitle: "新字段测试",  // 您的新字段
});
console.log(result);

CLI检查

npx bknd debug paths
# 在输出中检查实体字段

DOs和DON’Ts

DO:

  • 使用蛇形命名作为字段名称
  • 从可选字段开始；如果需要再设为必需
  • 对现有数据的必需字段添加默认值
  • 使用适当的字段类型（不要将数字存储为文本）

DON’T:

  • 使用 enum 导入（使用 enumm）
  • 在没有默认值的情况下对现有实体添加 .required()
  • 使用驼峰命名或帕斯卡命名作为字段名称
  • 创建冗余字段（例如 id 是自动生成的）

相关技能

  • bknd-create-entity - 首先创建新实体
  • bknd-define-relationship - 添加实体间关系
  • bknd-modify-schema - 重命名或更改字段类型
  • bknd-crud-create - 使用新字段插入数据