Python开发技巧--类型注解Literal

乱写代码2026-07-14 17:38

查看LangChain源码时，发现Literal：

python 复制代码

class Document(BaseMedia):
    """Class for storing a piece of text and associated metadata.

    !!! note

        `Document` is for **retrieval workflows**, not chat I/O. For sending text
        to an LLM in a conversation, use message types from `langchain.messages`.

    Example:
        ```python
        from langchain_core.documents import Document

        document = Document(
            page_content="Hello, world!", metadata={"source": "https://example.com"}
        )
        ```
    """

    page_content: str
    """String text."""

    type: Literal["Document"] = "Document"

作用：静态代码检查时，如果type为其他值，即!="Document"，会发生报错。注：在不实际运行程序（不执行代码）的情况下，通过分析源代码的文本结构来找出潜在的错误。

进一步，LangChain 框架中的深层作用

序列化时的"防伪标签" 当 LangChain 将 Document 对象转换成 JSON 字符串时，type: Literal $"Document"$ 保证了输出的 JSON 里一定会包含这个标签如下：

python 复制代码

print(f"转换格式后：\n{json.dumps(document1_json, ensure_ascii=False, indent=2)}")

# 转换格式后，{
#   "lc": 1,
#   "type": "constructor",
#   "id": [
#     "langchain",
#     "schema",
#     "document",
#     "Document"
#   ],
#   "kwargs": {
#     "metadata": {
#       "author": "张三",
#       "page": 10
#     },
#     "page_content": "LangChain 是一个用于开发大语言模型应用的框架。",
#     "type": "Document" 
#   }
# }

配合 Pydantic 的运行时校验 Pydantic 会直接抛出验证错误，防止脏数据污染系统

例子：

python 复制代码

from pydantic import BaseModel
from typing import Literal

class MyClass(BaseModel):
    type: Literal["red"] = "red"

obj = MyClass()
obj.type = "Image"  # ❌ Pydantic 会在运行时抛出 ValidationError