7.3 · 接口参考（API Reference）

企业电子文档治理 · 本章是 Mayan EDMS DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Mayan EDMS 章节7.3 状态全文译文模块文档对象与元数据、接口与服务契约、认证、权限与安全、系统架构

项目要点页2.5 参考项目项目章节目录Mayan EDMS DeepWiki 原始章节API Reference 上一章7.2

源码线索

mayan/apps/cabinets/tests/test_wizard_steps.py
mayan/apps/cabinets/wizard_steps.py
mayan/apps/dependencies/dependencies.py
mayan/apps/documents/apps.py
mayan/apps/documents/icons.py
mayan/apps/documents/links/document_version_links.py
mayan/apps/documents/managers.py
mayan/apps/documents/permissions.py
mayan/apps/documents/tasks.py
mayan/apps/documents/urls.py

模块标签

文档对象与元数据
接口与服务契约
认证、权限与安全
系统架构
测试、发布与运维

中文译文

接口参考（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mayan-edms/Mayan-EDMS/7.3-api-reference

翻译时间：2026-05-27T08:44:36.333Z

翻译模型：deepseek-chat

原文字符数：23046

项目：Mayan EDMS (mayan-edms)

---

API 参考

目的与范围

本文档提供 Mayan EDMS REST API 的全面参考文档，包括端点规范、认证机制、请求/响应格式以及序列化模式。该 API 支持以编程方式访问文档管理、元数据处理、源配置和工作流操作。

有关底层数据模型和数据库模式的信息，请参阅数据模型参考。有关 API 相关配置设置和部署选项，请参阅配置参考。

API 架构总览

整体 API 结构

graph TB
    subgraph "客户端层"
        API_CLIENT[API 客户端]
        BROWSER[Web 浏览器]
        MOBILE[移动应用]
    end

    subgraph "API 网关层"
        DRF[Django REST Framework]
        API_ROUTER[API 路由器]
        AUTH[认证层]
        PERMS[权限系统]
    end

    subgraph "应用层"
        DOC_API[documents.api_views]
        SRC_API[sources.api_views]
        META_API[metadata.api_views]
        OTHER_API[其他应用 API]
    end

    subgraph "序列化层"
        DOC_SER[DocumentSerializer]
        SRC_SER[SourceSerializer]
        META_SER[MetadataTypeSerializer]
        DYN_SER[DynamicSerializerField]
    end

    subgraph "模型层"
        DOC_MODEL[Document]
        SRC_MODEL[Source]
        META_MODEL[MetadataType]
        ACL_MODEL[AccessControlList]
    end

    API_CLIENT --> DRF
    BROWSER --> DRF
    MOBILE --> DRF

    DRF --> API_ROUTER
    API_ROUTER --> AUTH
    AUTH --> PERMS

    PERMS --> DOC_API
    PERMS --> SRC_API
    PERMS --> META_API
    PERMS --> OTHER_API

    DOC_API --> DOC_SER
    SRC_API --> SRC_SER
    META_API --> META_SER

    DOC_SER --> DYN_SER
    SRC_SER --> DYN_SER
    META_SER --> DYN_SER

    DYN_SER --> DOC_MODEL
    DYN_SER --> SRC_MODEL
    DYN_SER --> META_MODEL

    PERMS --> ACL_MODEL

来源：mayan/apps/documents/urls.py:522-688, mayan/apps/sources/urls.py:73-86, mayan/apps/metadata/urls.py:100-129, mayan/apps/rest_api/fields.py:30, mayan/apps/documents/apps.py:285-287

URL 路由结构

graph LR
    subgraph "API URL 模式"
        ROOT["/api/"] --> DOCS_ROOT["/documents/"]
        ROOT --> SRC_ROOT["/sources/"]
        ROOT --> META_ROOT["/metadata_types/"]
        ROOT --> DOC_TYPES["/document_types/"]

        DOCS_ROOT --> DOC_LIST["APIDocumentListView"]
        DOCS_ROOT --> DOC_UPLOAD["APIDocumentUploadView"]
        DOCS_ROOT --> DOC_DETAIL["APIDocumentDetailView"]

        SRC_ROOT --> SRC_LIST["APISourceListView"]
        SRC_ROOT --> SRC_DETAIL["APISourceView"]
        SRC_ROOT --> SRC_ACTION["APISourceActionDetailView"]

        META_ROOT --> META_LIST["APIMetadataTypeListView"]
        META_ROOT --> META_DETAIL["APIMetadataTypeView"]

        DOC_TYPES --> DOCTYPE_META["APIDocumentTypeMetadataTypeListView"]
    end

    subgraph "嵌套资源"
        DOC_DETAIL --> DOC_FILES["document-files"]
        DOC_DETAIL --> DOC_VERSIONS["document-versions"]
        DOC_DETAIL --> DOC_META["document-metadata"]

        DOC_FILES --> FILE_PAGES["file-pages"]
        DOC_VERSIONS --> VERSION_PAGES["version-pages"]
    end

来源：mayan/apps/documents/urls.py:522-688, mayan/apps/sources/urls.py:73-86, mayan/apps/metadata/urls.py:100-129

核心 API 端点

文档管理端点

HTTP 方法	端点	视图类	用途
GET, POST	`/api/documents/`	`APIDocumentListView`	列出/创建文档
POST	`/api/documents/upload/`	`APIDocumentUploadView`	上传新文档
GET, PUT, PATCH, DELETE	`/api/documents/{id}/`	`APIDocumentDetailView`	文档操作
POST	`/api/documents/{id}/type/change/`	`APIDocumentChangeTypeView`	更改文档类型

来源：mayan/apps/documents/urls.py:522-564

文档文件管理

HTTP 方法	端点	视图类	用途
GET	`/api/documents/{id}/files/`	`APIDocumentFileListView`	列出文档文件
GET, PUT, PATCH, DELETE	`/api/documents/{id}/files/{file_id}/`	`APIDocumentFileDetailView`	文件操作
GET	`/api/documents/{id}/files/{file_id}/download/`	`APIDocumentFileDownloadView`	下载文件
GET	`/api/documents/{id}/files/{file_id}/pages/`	`APIDocumentFilePageListView`	列出文件页面

来源：mayan/apps/documents/urls.py:566-596

源管理

HTTP 方法	端点	视图类	用途
GET, POST	`/api/sources/`	`APISourceListView`	列出/创建源
GET, PUT, PATCH, DELETE	`/api/sources/{id}/`	`APISourceView`	源操作
GET, POST	`/api/sources/{id}/actions/{action}/`	`APISourceActionDetailView`	执行源操作

来源：mayan/apps/sources/urls.py:73-86

元数据管理

HTTP 方法	端点	视图类	用途
GET, POST	`/api/metadata_types/`	`APIMetadataTypeListView`	列出/创建元数据类型
GET, PUT, PATCH, DELETE	`/api/metadata_types/{id}/`	`APIMetadataTypeView`	元数据类型操作
GET, POST	`/api/documents/{id}/metadata/`	`APIDocumentMetadataListView`	文档元数据
GET, PUT, PATCH, DELETE	`/api/documents/{id}/metadata/{meta_id}/`	`APIDocumentMetadataView`	元数据操作

来源：mayan/apps/metadata/urls.py:100-129

认证与权限

权限系统集成

graph TB
    subgraph "API 请求流程"
        REQUEST[HTTP 请求] --> AUTH_CHECK[认证检查]
        AUTH_CHECK --> USER_RESOLVE[用户解析]
        USER_RESOLVE --> PERM_CHECK[权限检查]
        PERM_CHECK --> ACL_EVAL[ACL 评估]
        ACL_EVAL --> VIEW_EXEC[视图执行]
    end

    subgraph "权限类"
        PERM_CHECK --> OBJ_PERMS[mayan_object_permissions]
        PERM_CHECK --> VIEW_PERMS[mayan_view_permissions]
        PERM_CHECK --> EXT_PERMS[mayan_external_object_permissions]
    end

    subgraph "ACL 系统"
        ACL_EVAL --> ACL_MODEL[AccessControlList]
        ACL_EVAL --> RESTRICT_QS[restrict_queryset]
        ACL_MODEL --> ROLES[角色分配]
        ACL_MODEL --> MODEL_PERMS[ModelPermission]
    end

来源：mayan/apps/metadata/api_views.py:31-37, mayan/apps/sources/api_views.py:21-24, mayan/apps/documents/apps.py:437-486

权限模式

API 使用三种主要的权限模式：

对象权限（mayan_object_permissions）：应用于特定的模型实例
视图权限（mayan_view_permissions）：应用于整个视图/端点
外部对象权限（mayan_external_object_permissions）：应用于相关对象

来源：mayan/apps/metadata/api_views.py:31-37, mayan/apps/sources/api_views.py:105-109

序列化系统

动态字段选择

graph LR
    subgraph "序列化器注册"
        APP_READY[AppConfig.ready] --> DYN_REG[DynamicSerializerField.add_serializer]
        DYN_REG --> DOC_SER_REG[Document -> DocumentSerializer]
        DYN_REG --> SRC_SER_REG[Source -> SourceSerializer]
    end

    subgraph "运行时序列化"
        API_REQ[API 请求] --> SER_SEL[序列化器选择]
        SER_SEL --> FIELD_DYN[动态字段解析]
        FIELD_DYN --> RESP_BUILD[响应构建]
    end

    subgraph "核心序列化器"
        DOC_SER[DocumentSerializer]
        SRC_SER[SourceSerializer]
        META_SER[MetadataTypeSerializer]
        DOC_META_SER[DocumentMetadataSerializer]
    end

来源：mayan/apps/documents/apps.py:285-287, mayan/apps/sources/apps.py:72-74, mayan/apps/rest_api/fields.py:30

关键序列化器类

序列化器类	模型	用途	文件位置
`DocumentSerializer`	`Document`	文档表示	documents.serializers
`SourceSerializer`	`Source`	源配置	sources.serializers
`MetadataTypeSerializer`	`MetadataType`	元数据类型定义	metadata.serializers
`DocumentMetadataSerializer`	`DocumentMetadata`	文档元数据值	metadata.serializers

来源：mayan/apps/metadata/serializers.py:24-37, mayan/apps/sources/serializers.py:10-21

请求/响应模式

文档上传流程

sequenceDiagram
    participant CLIENT as API 客户端
    participant UPLOAD as APIDocumentUploadView
    participant TASK as task_document_upload
    participant SOURCE as 源
    participant DOC as 文档

    CLIENT->>UPLOAD: POST /api/documents/upload/
    UPLOAD->>TASK: 排队上传任务
    TASK->>SOURCE: handle_file_object_upload
    SOURCE->>DOC: 创建文档
    DOC->>TASK: 文档已创建
    TASK->>CLIENT: 返回包含文档数据的响应

来源：mayan/apps/documents/tasks.py:140-194, mayan/apps/sources/models.py:87-161

元数据管理流程

sequenceDiagram
    participant CLIENT as API 客户端
    participant META_API as APIDocumentMetadataListView
    participant VALID as 校验
    participant META_MODEL as DocumentMetadata
    participant EVENT as 事件系统

    CLIENT->>META_API: POST /api/documents/{id}/metadata/
    META_API->>VALID: 校验元数据类型
    VALID->>META_MODEL: 创建元数据实例
    META_MODEL->>EVENT: 触发 metadata_added 事件
    EVENT->>CLIENT: 返回已创建的元数据

来源：mayan/apps/metadata/api_views.py:22-55, mayan/apps/metadata/serializers.py:88-144

源操作系统

源后端操作

graph TB
    subgraph "源操作执行"
        ACTION_REQ[操作请求] --> SOURCE_GET[获取源实例]
        SOURCE_GET --> BACKEND_GET[获取后端实例]
        BACKEND_GET --> ACTION_VALID[校验操作]
        ACTION_VALID --> ACTION_EXEC[执行操作方法]
        ACTION_EXEC --> RESP_BUILD[构建响应]
    end

    subgraph "后端类"
        BACKEND_GET --> SRC_BACKEND[SourceBackend]
        SRC_BACKEND --> WEB_FORM[WebFormSourceBackend]
        SRC_BACKEND --> SANE_SCAN[SANESourceBackend]
        SRC_BACKEND --> OTHER_BACK[其他后端]
    end

    subgraph "操作类型"
        ACTION_EXEC --> UPLOAD_ACT[上传操作]
        ACTION_EXEC --> SCAN_ACT[扫描操作]
        ACTION_EXEC --> PROCESS_ACT[处理操作]
    end

来源：mayan/apps/sources/api_views.py:15-97, mayan/apps/sources/classes.py:91-232

操作配置

源操作使用 SourceBackendAction 命名元组定义，包含以下字段：

name：操作标识符
accept_files：操作是否接受文件上传
arguments：必需参数
confirmation：是否需要确认
method：要执行的后端方法

来源：mayan/apps/sources/classes.py:91-108

错误处理与状态码

标准 HTTP 状态码

状态码	用途	示例场景
200 OK	成功的 GET、PUT、PATCH	文档已检索、元数据已更新
201 Created	成功的 POST	文档已创建、元数据已添加
204 No Content	成功的 DELETE	文档已删除、元数据已移除
400 Bad Request	校验错误	无效的元数据值、缺少必填字段
401 Unauthorized	需要认证	未提供有效凭证
403 Forbidden	权限被拒绝	用户缺少所需权限
404 Not Found	资源未找到	文档 ID 不存在

校验错误格式

API 校验错误遵循 Django REST Framework 约定：

{
    "field_name": ["该字段的错误消息"],
    "non_field_errors": ["通用校验错误"]
}

来源：mayan/apps/metadata/serializers.py:118-144

集成示例

创建文档并附带元数据

POST /api/documents/upload/
Content-Type: multipart/form-data

{
    "document_type_id": 1,
    "file": "<文件数据>",
    "metadata": [
        {
            "metadata_type_id": 1,
            "value": "发票 #12345"
        }
    ]
}

执行源操作

POST /api/sources/1/actions/upload/
Content-Type: application/json

{
    "arguments": {
        "document_type_id": 1,
        "expand": false
    },
    "file": "<文件数据>"
}

来源：mayan/apps/sources/api_views.py:51-62, mayan/apps/metadata/api_views.py:50-54