denimgroup/crudapi

tn-crud-api Docker镜像文档

概述

tn-crud-api是一个预配置的RESTful API服务Docker镜像，旨在提供快速部署的数据管理后端解决方案。该镜像封装了完整的CRUD操作功能，允许开发人员和系统管理员无需从零开始构建API服务，即可快速实现对数据库资源的管理。

核心功能与特性

• 完整CRUD支持：提供标准的创建(POST)、读取(GET)、更新(PUT/PATCH)和删除(DELETE)操作
• 多数据库支持：兼容MySQL、PostgreSQL和SQLite等主流关系型数据库
• 自动API生成：根据数据库模式自动生成对应的API端点
• RESTful设计：遵循REST最佳实践，提供直观的API路径结构
• 数据验证：内置请求数据验证机制，确保数据完整性
• JSON格式支持：所有API响应均采用JSON格式，便于客户端解析
• CORS支持：内置跨域资源共享配置，方便前端应用集成
• 安全特性：包含基础认证、请求速率限制和SQL注入防护

使用场景

• 快速原型开发：加速后端API服务搭建
• 小型应用后端：为前端应用提供简单的数据存储和管理接口
• 内部管理系统：快速构建部门或团队内部的数据管理工具
• 微服务架构：作为整体系统中的数据服务组件
• 教学和演示环境：学习RESTful API设计和实现的示例

适用范围

• 中小型应用的数据管理后端
• 快速原型验证
• 内部业务系统
• 低代码/无代码平台后端
• 教学和开发测试环境

部署与使用

基本使用（Docker Run）

bash
docker run -d -p 3000:3000 --name tn-crud-api \
  -e DATABASE_URL="mysql://user:password@host:port/dbname" \
  -e API_PREFIX="/api" \
  -e AUTH_ENABLED="false" \
  tn-crud-api:latest

Docker Compose配置

yaml
version: '3'
services:
  api:
    image: tn-crud-api:latest
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL="postgresql://user:password@db:5432/mydatabase"
      - API_PREFIX="/api/v1"
      - PORT=3000
      - AUTH_ENABLED="true"
      - AUTH_SECRET="your-secret-key"
    depends_on:
      - db
  db:
    image: postgres:13
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=mydatabase
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

环境变量配置

数据库支持

tn-crud-api支持以下数据库类型，通过DATABASE_URL参数指定：

• MySQL/MariaDB: mysql://user:password@host:port/database
• PostgreSQL: postgresql://user:password@host:port/database
• SQLite: sqlite:///path/to/database.db
• MongoDB: mongodb://user:password@host:port/database

API端点

部署后，默认API端点结构如下：

• GET /{API_PREFIX}/{resource} - 获取资源列表
• GET /{API_PREFIX}/{resource}/{id} - 获取单个资源
• POST /{API_PREFIX}/{resource} - 创建新资源
• PUT /{API_PREFIX}/{resource}/{id} - 更新资源
• DELETE /{API_PREFIX}/{resource}/{id} - 删除资源

持久化数据

为确保数据持久化，建议使用Docker卷挂载数据库存储目录或使用外部数据库服务。对于SQLite，可通过以下方式挂载数据卷：

bash
docker run -d -p 3000:3000 \
  -v ./data:/app/data \
  -e DATABASE_URL="sqlite:////app/data/db.sqlite" \
  tn-crud-api:latest

健康检查

容器内置健康检查机制，可通过以下命令查看服务状态：

bash
docker inspect --format='{{json .State.Health}}' tn-crud-api

日志查看

查看API服务日志：

bash
docker logs tn-crud-api

实时查看日志：

bash
docker logs -f tn-crud-api

常见问题

如何自定义API端点？

目前不支持直接自定义API端点，需通过修改源代码实现。建议使用API_PREFIX环境变量区分不同版本或服务。

如何添加认证？

设置AUTH_ENABLED=true并提供AUTH_SECRET，然后在请求头中使用Authorization: Bearer <token>进行认证。

服务启动失败怎么办？

检查数据库连接是否正确，日志中是否有错误信息，确保数据库服务可访问且凭证正确。