# 数据库总览
# 一、简介
土豆 API 提供灵活的数据库管理能力，支持两种数据库接入方式，适用于不同场景下的开发需求：
- 系统默认数据库：由土豆 API 平台统一维护，无需额外配置，适合快速构建业务逻辑。
- 用户自建数据库：用户可以接入自建的 MySQL、PostgreSQL 等数据库，实现数据统一接入与管理。
通过土豆 API 的网页控制端，开发者可以完成数据源配置、表结构管理、数据增删改查等全套操作，极大地提升开发效率。
# 二、数据源配置流程
# 2.1 创建数据源
进入网页控制台的「数据源配置」页面，点击「新建数据源」，选择以下两种方式之一：
系统默认数据源：平台为您自动配置，无需提供连接信息，适合大多数业务使用。
自建数据源：您需填写如下信息接入外部数据库：
- 数据源名称
- 数据库类型（MySQL、PostgreSQL 等）
- 数据库地址（Host + Port）
- 数据库名称
- 用户名 / 密码
所有连接信息在存储前将经过加密处理，确保数据安全。
# 2.2 创建数据表
在数据源配置完成后，点击该数据源进入「数据源表」模块，可创建用于 API 访问的数据表。
创建表时可设置以下信息：
| 参数 | 描述 |
|---|---|
| 表名称 | 唯一标识该表的名称 |
| 表备注 | 可选的说明文字，便于理解表的用途 |
| 开启读权限 | 允许通过 API 读取该表数据 |
| 开启写权限 | 允许通过 API 修改、插入或删除数据 |
# 三、默认字段说明
每个新创建的数据表将默认包含以下字段，系统自动维护：
| 字段名 | 类型 | 描述 |
|---|---|---|
id | 整型，自增 | 主键，自增，唯一标识每条记录 |
created_at | 时间戳 | 创建时间，系统自动填充 |
updated_at | 时间戳 | 最后修改时间，系统自动更新 |
这些字段为系统级字段，无需手动添加，也建议不要删除或修改。
# 四、表结构与数据管理
# 4.1 字段操作
支持如下字段管理操作：
添加字段：支持所有常见类型（除二进制类型）：
- 整型（int, bigint 等）
- 浮点型（float, double 等）
- 字符串（varchar, text 等）
- 布尔（boolean）
- 时间/日期（datetime, timestamp 等）
- JSON、枚举等结构化类型
修改字段：支持修改字段名称、类型、默认值、备注等。
删除字段：可删除非系统默认字段。
# 4.2 数据操作
- 添加新数据记录
- 修改已有记录的字段值
- 删除记录（支持批量删除）
- 表内数据支持分页浏览、条件筛选
# 五、数据源应用场景示例
土豆 API 的数据源机制设计灵活，适用于多种业务开发场景，以下是一些常见应用示例：
# 5.1 表单系统
结合土豆 API 提供的数据库读写能力，可快速构建自定义表单系统：
- 用户在前端提交表单数据
- 表单字段自动映射到数据源表字段
- 后台通过 API 存储、查询、筛选数据
# 5.2 业务配置中心
将系统中的可配置项存入数据源表，例如：
- 权限配置
- 参数模板
- 策略规则集
可以在后台动态修改配置，而不需频繁更改代码。
# 5.3 日志与事件追踪
使用数据源表作为日志落地方案，记录系统行为或用户操作事件：
- 创建一个日志表（log_events）
- 通过 API 写入操作行为、用户 ID、时间戳等
- 配合分页与筛选，可快速分析历史操作记录
# 5.4 多租户 SaaS 管理
在自建数据源中创建多张表，按租户维度隔离数据：
- 每个租户一个逻辑表或字段标识
- 管理端统一调用数据源 API 完成数据汇总或分离
- 保证数据隔离的同时简化后台开发成本
这些场景都可以结合土豆 API 的数据源能力实现快速开发部署，提升业务迭代效率。
# 六、数据源 API 使用说明
在数据源与数据表配置完成后，即可通过土豆 API 提供的接口进行调用，支持标准的 CRUD 操作：
- 创建数据（Create）
- 读取数据（Read）
- 更新数据（Update）
- 删除数据（Delete）
API 使用时需提供数据源标识、表名称及对应的字段参数，平台会自动校验权限并完成操作。
同时支持以下功能：
- 条件查询（支持表达式）
- 排序、分页、筛选
- 批量操作（批量插入、更新、删除）
所有 API 均需通过 Token 或 API Key 进行授权调用，确保接口调用安全。
# 七、安全说明
为保障数据库访问的安全性，土豆 API 在系统架构中采用如下措施：
- 所有数据库连接信息（账号、密码等）均经过加密存储，不会以明文形式保存。
- 系统使用 HTTPS 协议进行数据传输，确保链路加密。
- 数据源的读写权限控制可在控制台中配置，避免非法操作。
- 所有 API 接口均需授权访问，支持 API Key 或 Token 鉴权机制。
推荐使用内网或 VPN 访问自建数据库，避免直接暴露公网端口。
# 云端数据库 VS 本地数据库的安全性
与传统的本地部署数据库相比，云端数据库在安全性方面具有以下明显优势：
- 自动加密存储：云端数据库通常内置数据加密机制（如磁盘加密、传输加密），避免明文泄露。
- 高可用架构：系统故障时自动切换到备份节点，保障业务连续性。
- 统一访问控制：通过 API 网关、权限系统、Token 鉴权统一管理访问权限，避免裸露连接。
- 物理安全保障：云平台的数据中心具备严格的物理和网络安全措施，远优于普通企业服务器机房。
- 自动备份与灾备：可定期自动备份数据，降低意外数据丢失风险。
建议优先使用土豆 API 提供的云端数据库或接入云数据库平台，如阿里云、腾讯云、AWS RDS 等，以获得更好的安全性与运维便利。