NocoDB API与SDK：程序化访问与二次开发-优快云博客

NocoDB API与SDK：程序化访问与二次开发

【免费下载链接】nocodb nocodb/nocodb: 是一个基于 node.js 和 SQLite 数据库的开源 NoSQL 数据库，它提供了可视化的 Web 界面用于管理和操作数据库。适合用于构建简单的 NoSQL 数据库，特别是对于需要轻量级、易于使用的数据库场景。特点是轻量级、易于使用、基于 node.js 和 SQLite 数据库。项目地址: https://gitcode.com/GitHub_Trending/no/nocodb

NocoDB提供了全面且强大的RESTful API接口和功能丰富的SDK，允许开发者通过编程方式访问和管理数据库资源。API采用分层架构设计，遵循REST原则，提供直观的端点结构和丰富的功能支持，包括认证授权、数据管理、表结构管理等核心功能。SDK则提供了完整的开发工具包，采用模块化设计，包含数据处理、过滤构建、公式计算、权限控制等强大功能，为开发者提供与NocoDB平台进行程序化交互的完整解决方案。

REST API设计与使用指南

NocoDB提供了全面且强大的RESTful API接口，允许开发者通过编程方式访问和管理数据库资源。其API设计遵循REST原则，提供了直观的端点结构和丰富的功能支持。

API架构设计

NocoDB的REST API采用分层架构设计，主要分为以下几个层次：

mermaid

核心API端点结构

NocoDB的API端点采用清晰的命名约定，主要分为以下几个类别：

1. 认证与授权端点

端点	方法	描述	示例
`/api/v1/auth/user/signin`	POST	用户登录	`curl -X POST /api/v1/auth/user/signin -d '{"email":"user@example.com","password":"password"}'`
`/api/v1/auth/user/signup`	POST	用户注册	`curl -X POST /api/v1/auth/user/signup -d '{"email":"user@example.com","password":"password"}'`
`/api/v1/auth/token/refresh`	POST	刷新访问令牌	`curl -X POST /api/v1/auth/token/refresh -d '{"refresh_token":"token"}'`
`/api/v1/db/meta/projects/:baseId/api-tokens`	POST	创建API令牌	`curl -X POST /api/v1/db/meta/projects/base123/api-tokens -H "Authorization: Bearer {token}"`

2. 数据管理端点

数据操作是NocoDB API的核心功能，支持完整的CRUD操作：

mermaid

3. 表结构管理端点

端点	方法	描述	权限要求
`/api/v1/db/meta/projects/:baseId/tables`	GET	获取表列表	`tableList`
`/api/v1/db/meta/projects/:baseId/tables`	POST	创建新表	`tableCreate`
`/api/v1/db/meta/tables/:tableId`	GET	获取表详情	`tableGet`
`/api/v1/db/meta/tables/:tableId`	PATCH	更新表结构	`tableUpdate`
`/api/v1/db/meta/tables/:tableId`	DELETE	删除表	`tableDelete`

认证机制

NocoDB支持多种认证方式，确保API访问的安全性：

JWT令牌认证

// 使用JWT令牌进行API调用示例
const axios = require('axios');

const API_BASE = 'http://localhost:8080';
const API_TOKEN = 'your_jwt_token_here';

const client = axios.create({
  baseURL: API_BASE,
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

// 获取项目列表
async function getProjects() {
  try {
    const response = await client.get('/api/v1/db/meta/projects');
    return response.data;
  } catch (error) {
    console.error('API调用失败:', error.response?.data);
    throw error;
  }
}

API密钥认证

// 使用API密钥进行curl请求
curl -X GET "http://localhost:8080/api/v1/db/meta/projects" \
  -H "xc-auth: your_api_key_here" \
  -H "Content-Type: application/json"

数据操作示例

插入数据

// 插入单条数据
const newRecord = {
  fields: {
    Name: "John Doe",
    Email: "john@example.com",
    Age: 30,
    Status: "Active"
  }
};

const response = await client.post('/data/views/view123', newRecord);
console.log('创建记录ID:', response.data.records[0].id);

查询数据

// 带过滤条件的查询
const queryParams = {
  where: '(Name,eq,John Doe)',
  sort: '-CreatedAt',
  limit: 10,
  offset: 0
};

const response = await client.get('/data/views/view123', { params: queryParams });
console.log('查询结果:', response.data.records);

更新数据

// 更新指定记录
const updateData = {
  fields: {
    Status: "Inactive",
    LastModified: new Date().toISOString()
  }
};

const response = await client.patch('/data/views/view123/row456', updateData);
console.log('更新成功:', response.data);

删除数据

// 删除记录
const response = await client.delete('/data/views/view123/row456');
console.log('删除成功:', response.data);

高级查询功能

NocoDB提供了强大的查询功能，支持复杂的过滤、排序和分页：

过滤语法

// 多条件过滤示例
const filters = {
  where: '(Status,eq,Active)~and(Age,gt,25)~or(Department,eq,Sales)',
  sort: 'Name,-CreatedAt', // 多个排序字段
  fields: 'Name,Email,Status' // 指定返回字段
};

const response = await client.get('/data/views/view123', { params: filters });

关系数据查询

// 查询关联数据（Has-Many关系）
const relatedData = await client.get('/data/views/view123/row456/hm/DepartmentCol');

// 查询多对多关系数据
const manyToManyData = await client.get('/data/views/view123/row456/mm/ProjectsCol');

错误处理与响应格式

NocoDB API使用标准化的错误响应格式：

{
  "msg": "错误描述信息",
  "code": "错误代码",
  "details": {
    "field": "具体错误详情"
  }
}

常见HTTP状态码

状态码	含义	典型场景
200	成功	查询、更新操作成功
201	创建成功	新记录创建成功
400	错误请求	参数验证失败
401	未授权	认证失败
403	禁止访问	权限不足
404	未找到	资源不存在
500	服务器错误	内部处理错误

批量操作支持

NocoDB支持批量数据操作，提高处理效率：

// 批量插入示例
const batchRecords = {
  records: [
    {
      fields: { Name: "User1", Email: "user1@example.com" }
    },
    {
      fields: { Name: "User2", Email: "user2@example.com" }
    }
  ]
};

const response = await client.post('/api/v1/db/data/bulk/views/view123', batchRecords);

实时数据订阅

通过WebSocket支持实时数据更新：

// WebSocket实时数据订阅示例
const WebSocket = require('ws');
const ws = new WebSocket('ws://localhost:8080/ws');

ws.on('open', function open() {
  // 订阅表数据变化
  ws.send(JSON.stringify({
    type: 'subscribe',
    id: 'table-123',
    data: { tableId: 'table123' }
  }));
});

ws.on('message', function message(data) {
  console.log('实时数据更新:', JSON.parse(data));
});

性能优化建议

使用字段选择：通过fields参数只请求需要的字段
合理分页：使用limit和offset进行分页查询
缓存响应：对不经常变化的数据实施缓存策略
批量操作：使用批量接口减少请求次数
异步处理：对耗时操作使用异步处理模式

安全最佳实践

使用HTTPS加密通信
定期轮换API密钥和JWT令牌
实施最小权限原则
监控和记录API访问日志
使用速率限制防止滥用

NocoDB的REST API设计既考虑了开发者的易用性，又确保了企业级的安全性和性能要求。通过合理的API设计模式和丰富的功能支持，开发者可以轻松构建基于NocoDB的应用程序。

NocoDB SDK功能详解

NocoDB SDK是一个功能强大的开发工具包，为开发者提供了与NocoDB平台进行程序化交互的完整解决方案。通过SDK，开发者可以轻松地在自己的应用程序中集成数据库操作、数据管理、权限控制等核心功能，实现与NocoDB的无缝对接。

SDK核心架构与模块设计

NocoDB SDK采用模块化设计，将功能划分为多个独立的模块，每个模块负责特定的功能领域。这种设计使得SDK既保持了功能的完整性，又具备了良好的可扩展性和维护性。

mermaid

核心API模块功能

基础HTTP客户端

SDK的核心是Api类，它封装了与NocoDB服务器通信的所有HTTP操作。该类提供了完整的RESTful API支持：

// 初始化API客户端
const api = new Api({
  baseURL: 'https://your-nocodb-instance.com',
  headers: {
    'xc-auth': 'your-api-token'
  }
});

// 执行CRUD操作
const tables = await api.get('/api/v1/db/meta/projects/:projectId/tables');
const records = await api.get('/api/v1/db/data/:tableId');
const newRecord = await api.post('/api/v1/db/data/:tableId', { data });
const updatedRecord = await api.patch('/api/v1/db/data/:tableId/:recordId', { data });
const deleted = await api.delete('/api/v1/db/data/:tableId/:recordId');

自定义API端点支持

CustomAPI类允许开发者执行自定义的API端点，支持文件上传等高级功能：

const customApi = new CustomAPI(api);
const result = await customApi.executeCustomEndpoint('custom-endpoint-name', {
  method: 'POST',
  data: { param1: 'value1' }
});

// 文件上传示例
const uploadResult = await customApi.uploadFile(file, {
  path: '/uploads',
  fileName: 'document.pdf'
});

数据处理与过滤功能

高级过滤器构建器

FilterHelpers模块提供了强大的过滤条件构建功能，支持复杂的查询条件组合：

import { buildFilterQuery } from 'nocodb-sdk/lib/filterHelpers';

// 构建复杂过滤条件
const filter = buildFilterQuery({
  where: {
    and: [
      { field: 'status', op: 'eq', value: 'active' },
      { field: 'created_at', op: 'gt', value: '2024-01-01' },
      {
        or: [
          { field: 'category', op: 'in', value: ['tech', 'business'] },
          { field: 'priority', op: 'gte', value: 3 }
        ]
      }
    ]
  }
});

// 生成的过滤条件可用于API查询
const filteredData = await api.get('/api/v1/db/data/:tableId', {
  params: { filter }
});

支持的过滤操作符

NocoDB SDK支持丰富的过滤操作符，满足各种查询需求：

操作符	描述	示例
`eq`	等于	`{field: 'status', op: 'eq', value: 'active'}`
`neq`	不等于	`{field: 'status', op: 'neq', value: 'inactive'}`
`gt`	大于	`{field: 'age', op: 'gt', value: 18}`
`gte`	大于等于	`{field: 'score', op: 'gte', value: 60}`
`lt`	小于	`{field: 'price', op: 'lt', value: 100}`
`lte`	小于等于	`{field: 'quantity', op: 'lte', value: 10}`
`in`	在列表中	`{field: 'category', op: 'in', value: ['A','B']}`
`notin`	不在列表中	`{field: 'id', op: 'notin', value: [1,2,3]}`
`like`	模糊匹配	`{field: 'name', op: 'like', value: 'john%'}`
`notlike`	不匹配	`{field: 'email', op: 'notlike', value: '%@test.com'}`

公式计算与数据处理

FormulaHelpers模块提供了强大的公式计算能力，支持在客户端执行复杂的数学运算和数据处理：

import { evaluateFormula, validateFormula } from 'nocodb-sdk/lib/formulaHelpers';

// 公式验证
const isValid = validateFormula('SUM({price} * {quantity})');
if (isValid) {
  // 公式计算
  const result = evaluateFormula('SUM({price} * {quantity})', {
    price: 25.99,
    quantity: 3
  });
  console.log(result); // 输出: 77.97
}

// 支持的高级公式函数
const complexResult = evaluateFormula(
  'IF({status} = "completed", {amount} * 0.1, 0) + MAX({bonus1}, {bonus2})',
  {
    status: 'completed',
    amount: 1000,
    bonus1: 50,
    bonus2: 75
  }
);

权限管理与访问控制

Permission模块提供了细粒度的权限控制功能，确保数据访问的安全性：

import { checkPermission, getUserRoles } from 'nocodb-sdk/lib/permission';

// 检查用户权限
const hasAccess = await checkPermission({
  resource: 'table',
  action: 'read',
  resourceId: 'table_123',
  userId: 'user_456'
});

// 获取用户角色信息
const userRoles = await getUserRoles('user_456');
console.log(userRoles); // 输出: ['admin', 'editor']

// 权限级别示例
const permissionLevels = {
  none: 0,      // 无权限
  read: 1,      // 只读权限
  comment: 2,   // 评论权限
  edit: 3,      // 编辑权限
  create: 4,    // 创建权限
  owner: 5      // 所有者权限
};

实时数据同步功能

Realtime模块提供了WebSocket-based的实时数据同步功能，支持数据变更的实时推送：

import { subscribe, unsubscribe } from 'nocodb-sdk/lib/realtime';

// 订阅数据变更
const subscription = subscribe('table:table_123', (event) => {
  console.log('数据变更:', event);
  // 事件类型包括: create, update, delete
});

// 取消订阅

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考