JavaScript、TypeScript 与 Python 的选择
1. 语言在 AI 应用中负责什么
使用托管模型 API 时,模型运行在服务提供方的服务器上。应用代码负责:
- 从界面、文件、数据库或其他服务取得输入;
- 把输入整理成 API 要求的 JSON 请求;
- 通过 HTTPS 发送请求;
- 检查状态码、解析响应、统计用量;
- 校验模型输出并执行后续业务逻辑;
- 记录日志,处理超时、限流、取消和重试;
- 向用户展示结果或把结果交给其他系统。
JavaScript、TypeScript 和 Python 都能完成这些工作。请求中的模型、输入、工具、输出格式与生成参数相同时,客户端语言不会自然提高模型质量。
训练模型或在本机运行模型时,语言还需要连接张量计算、数据处理、GPU 加速和分布式训练库。Python 在这些领域拥有更完整的工具链,但这不等于所有 AI 产品都必须使用 Python。
2. 语言、类型系统与运行时
这三个概念不能混为一谈。
| 概念 | 作用 | 例子 |
|---|---|---|
| 编程语言 | 规定语法、值、表达式和程序结构 | JavaScript、TypeScript、Python |
| 类型系统 | 检查值可以参与哪些操作 | TypeScript 的静态类型、Python 的类型提示 |
| 运行时 | 真正加载并执行程序 | 浏览器、Node.js、Python 解释器 |
2.1 JavaScript
JavaScript 是动态类型语言。变量本身没有固定类型,运行时的值有类型:
let result = "ready";
result = 3; // 合法,变量现在保存 number 值
console.log(typeof result); // "number"同一份语言可以运行在不同环境中,但环境提供的 API 不完全相同:
- 浏览器提供 DOM、页面事件、
localStorage等 Web API; - Node.js 提供服务端文件系统、进程、网络服务等能力;
fetch、URL、Streams 等一部分 Web API 同时存在于现代浏览器和 Node.js 中;- 浏览器中的代码交付给用户,不能保存长期服务端密钥;
- Node.js 代码可以读取服务器环境变量,但不能直接操作用户页面的 DOM。
2.2 TypeScript
TypeScript 是 JavaScript 的带类型语法。TypeScript 编译器在开发阶段检查类型,然后移除类型语法,输出 JavaScript:
type Usage = {
inputTokens: number;
outputTokens: number;
};
function total(usage: Usage): number {
return usage.inputTokens + usage.outputTokens;
}编译后的 JavaScript 不保留 Usage 类型。下面的写法只能表达开发者的预期,不能验证网络响应:
const data = (await response.json()) as Usage;as Usage 是类型断言。它不会检查 data 是否真的包含两个数字字段。外部数据需要运行时校验:
function isUsage(value: unknown): value is Usage {
if (typeof value !== "object" || value === null) return false;
const record = value as Record<string, unknown>;
return (
typeof record.inputTokens === "number" &&
typeof record.outputTokens === "number"
);
}TypeScript 适合约束以下结构:
- API 请求参数;
- 结构化输出;
- 工具调用参数和结果;
- 前端组件属性;
- 工作流状态;
- 领域对象和错误类型。
建议在 tsconfig.json 中启用 strict。它会开启一组更严格的类型检查,包括更严格的空值、函数参数和属性初始化检查。strict 仍然不验证运行时输入。
2.3 Python
Python 也是动态类型语言:
result = "ready"
result = 3
print(type(result).__name__) # intPython 类型提示用于编辑器、静态检查器、文档和框架集成:
from typing import TypedDict
class Usage(TypedDict):
input_tokens: int
output_tokens: int
def total(usage: Usage) -> int:
return usage["input_tokens"] + usage["output_tokens"]标准 Python 运行时不会因为函数收到错误类型而自动拒绝调用。JSON、模型输出和数据库记录仍需显式校验,或交给具有运行时校验能力的库处理。
Python 适合:
- 数据清洗和批处理;
- Notebook 实验;
- 离线评估;
- 传统机器学习与深度学习;
- 本地模型推理和训练;
- 后台任务、CLI 与数据服务。
3. 决策所需的六个维度
3.1 产品运行在哪里
| 主要运行位置 | 通常优先选择 | 原因 |
|---|---|---|
| 浏览器界面 | TypeScript | DOM、组件框架和浏览器工具链直接可用 |
| Node.js Web 服务 | TypeScript | 可与前端共享类型、Schema 和业务模型 |
| 数据脚本或 Notebook | Python | 数据、科学计算与实验工具成熟 |
| 模型训练或本地推理 | Python | 主流训练和张量计算生态优先支持 Python |
| CLI 与定时任务 | 两者都可 | 由现有仓库、依赖和部署平台决定 |
| 全栈 Web 产品 | TypeScript,或 TypeScript + Python | 单语言更简单;有独立数据/模型服务时再拆分 |
3.2 团队和现有代码
已有前端、Node.js 服务和 TypeScript 类型时,继续使用 TypeScript 通常能减少重复模型和部署单元。已有 Python 数据管道、评估集和模型代码时,Python 能直接复用数据处理逻辑。
不能只用“某语言更流行”作决定。应盘点:
- 已有领域模型和校验 Schema;
- 团队能审查和排错的语言;
- CI、日志、监控和部署设施;
- 必须使用的库是否支持目标语言;
- 最终维护者是否能独立运行项目。
3.3 类型与 Schema 边界
AI 应用存在大量不可信输入:用户文本、模型输出、HTTP 响应、工具参数和外部文件。无论选择哪种语言,都应在系统边界执行运行时校验。
flowchart LR
A["用户或外部系统"] --> B["运行时 Schema 校验"]
B -->|"有效"| C["类型明确的内部对象"]
B -->|"无效"| D["可处理的错误"]
C --> E["模型请求"]
E --> F["响应与结构化输出校验"]
F -->|"有效"| G["业务逻辑"]
F -->|"无效"| H["拒绝、修复或重试"]TypeScript 类型和 Python 类型提示约束的是内部开发过程;JSON Schema 或运行时校验器约束的是实际数据。
3.4 并发和流式响应
模型请求主要等待网络 I/O。两种语言都可以并发发送请求和消费流式响应:
- JavaScript 使用 Promise、
async/await、Streams 和事件; - Python 使用
asyncio、异步迭代器和异步 HTTP 客户端; - CPU 密集型预处理、模型推理与网络 I/O 的并发策略不同;
- 同时发出大量请求仍会受到 API 限流、连接数和预算约束。
不能用“JavaScript 异步,所以一定更快”或“Python 有机器学习库,所以 API 调用更快”作为判断。应使用目标工作负载测量吞吐、延迟、内存和失败率。
3.5 依赖与可复现环境
TypeScript/Node.js 项目通常记录:
package.json:依赖和脚本;- lockfile:解析后的准确依赖版本;
tsconfig.json:类型检查和编译选项;- Node.js 版本文件或部署配置:运行时版本。
Python 项目通常记录:
pyproject.toml:项目元数据、依赖和工具配置;- lockfile 或带哈希的依赖锁定结果;
.venv:本机隔离环境,不提交 Git;- Python 版本:避免只写模糊的“Python 3”。
.env 文件常用于本地配置,但包含真实密钥的文件不应提交。仓库可提供只含变量名和假值的 .env.example。
3.6 部署和运维
选择语言时必须确认目标环境:
- 是否支持所需运行时版本;
- 冷启动、内存和执行时长限制;
- 是否允许长连接或流式响应;
- 原生依赖是否能在目标 CPU 和操作系统运行;
- 日志、追踪、密钥管理和健康检查如何接入;
- 安全更新由谁负责。
4. 决策流程
flowchart TD
A["明确最终交付物"] --> B{"需要训练、本地推理或重度数据处理?"}
B -->|"是"| C["优先评估 Python"]
B -->|"否"| D{"主要产品是否是 Web,且已有 TypeScript?"}
D -->|"是"| E["优先 TypeScript"]
D -->|"否"| F{"某个必要库是否只在一种语言可用?"}
F -->|"是"| G["选择支持该能力的语言"]
F -->|"否"| H["选择团队最能维护和部署的语言"]
C --> I{"是否还需要复杂浏览器界面?"}
I -->|"是"| J["前端 TypeScript + 后端 Python"]
I -->|"否"| K["先使用单一 Python 项目"]推荐顺序:
- 初学者先用一种语言完成端到端项目;
- 只有出现明确能力边界时才引入第二种语言;
- 拆分后使用 HTTP、队列或版本化文件格式连接两个服务;
- 用共享 JSON Schema 或 OpenAPI 描述跨语言数据;
- 为边界增加契约测试,防止两边独立修改后不兼容。
5. 同一 API 任务的 TypeScript 实现
下面的示例运行在 Node.js 服务端,直接使用标准 fetch 展示 HTTP 边界。需要 Node.js 提供 fetch 和 TypeScript 执行/编译环境。
5.1 项目结构
ai-request-ts/
├── package.json
├── tsconfig.json
└── src/
└── main.tspackage.json:
{
"name": "ai-request-ts",
"private": true,
"type": "module",
"scripts": {
"check": "tsc --noEmit",
"build": "tsc",
"start": "node dist/main.js"
},
"devDependencies": {
"@types/node": "^24.0.0",
"typescript": "^5.0.0"
}
}tsconfig.json:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"outDir": "dist",
"types": ["node"],
"strict": true,
"noUncheckedIndexedAccess": true
},
"include": ["src"]
}5.2 请求、错误和响应解析
src/main.ts:
type ApiErrorBody = {
error?: {
message?: string;
type?: string;
code?: string | null;
};
};
type ResponseBody = {
output?: Array<{
type?: string;
content?: Array<{
type?: string;
text?: string;
}>;
}>;
usage?: {
input_tokens?: number;
output_tokens?: number;
total_tokens?: number;
};
};
const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) {
throw new Error("缺少 OPENAI_API_KEY 环境变量");
}
const model = process.env.OPENAI_MODEL;
if (!model) {
throw new Error("缺少 OPENAI_MODEL 环境变量");
}
function readOutputText(body: ResponseBody): string {
const texts = (body.output ?? []).flatMap((item) =>
(item.content ?? [])
.filter((content) => content.type === "output_text")
.map((content) => content.text)
.filter((text): text is string => typeof text === "string")
);
if (texts.length === 0) throw new Error("响应中没有 output_text 内容项");
return texts.join("");
}
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30_000);
try {
const response = await fetch("https://api.openai.com/v1/responses", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model,
input: "只返回数字:17 与 25 的和是多少?"
}),
signal: controller.signal
});
const requestId = response.headers.get("x-request-id");
const body: unknown = await response.json();
if (!response.ok) {
const errorBody = body as ApiErrorBody;
throw new Error(
`API ${response.status}:${errorBody.error?.message ?? "未知错误"}`
);
}
const result = body as ResponseBody;
console.log(readOutputText(result));
console.log({ requestId, usage: result.usage });
} finally {
clearTimeout(timeout);
}运行:
npm install
npm run check
npm run build
OPENAI_API_KEY="你的密钥" OPENAI_MODEL="你的模型标识" npm start这个示例中的类型断言只用于缩小演示范围。生产代码应使用运行时 Schema 校验响应;输出是数字字符串也不代表语义必然正确,仍应按业务规则验证。
6. 同一 API 任务的 Python 实现
下面使用 Python 标准库展示相同的 HTTP 请求,不依赖厂商 SDK。
6.1 创建隔离环境
python3 -m venv .venv
source .venv/bin/activate
python --versionWindows PowerShell 激活命令:
.venv\Scripts\Activate.ps1虚拟环境隔离第三方包,不隔离操作系统环境变量,也不是密钥仓库。
6.2 请求、错误和响应解析
main.py:
import json
import os
import urllib.error
import urllib.request
from typing import Any
api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
raise RuntimeError("缺少 OPENAI_API_KEY 环境变量")
model = os.environ.get("OPENAI_MODEL")
if not model:
raise RuntimeError("缺少 OPENAI_MODEL 环境变量")
payload = {
"model": model,
"input": "只返回数字:17 与 25 的和是多少?",
}
request = urllib.request.Request(
"https://api.openai.com/v1/responses",
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
method="POST",
)
try:
with urllib.request.urlopen(request, timeout=30) as response:
request_id = response.headers.get("x-request-id")
body: Any = json.loads(response.read().decode("utf-8"))
except urllib.error.HTTPError as error:
error_text = error.read().decode("utf-8", errors="replace")
raise RuntimeError(f"API {error.code}:{error_text}") from error
except urllib.error.URLError as error:
raise RuntimeError(f"网络请求失败:{error.reason}") from error
if not isinstance(body, dict):
raise RuntimeError("响应顶层不是 JSON 对象")
texts: list[str] = []
for item in body.get("output", []):
if not isinstance(item, dict):
continue
for content in item.get("content", []):
if not isinstance(content, dict):
continue
if content.get("type") == "output_text" and isinstance(content.get("text"), str):
texts.append(content["text"])
if not texts:
raise RuntimeError("响应中没有 output_text 内容项")
print("".join(texts))
print({"request_id": request_id, "usage": body.get("usage")})运行:
OPENAI_API_KEY="你的密钥" OPENAI_MODEL="你的模型标识" python main.pydict 检查和 output_text 检查只验证了本例使用的最小字段。更复杂的数据结构应使用完整的运行时 Schema。
7. SDK 与直接 HTTP 的区别
官方 SDK 通常提供:
- 请求和响应类型;
- 身份验证配置;
- 流式事件迭代;
- 超时、重试和错误对象;
- 文件上传等便利方法;
- 对最新 API 能力的语言封装。
直接 HTTP 的价值是明确协议边界,并能在没有目标语言 SDK 时调用 API。使用直接 HTTP 时,需要自行正确处理:
- URL、方法、请求头和 JSON 编码;
- 非 2xx 状态码;
- 请求超时和取消;
- 流式 SSE 事件;
- 重试等待、幂等性和限流;
- API 版本变化。
学习时应理解一次直接 HTTP 请求;项目实现通常优先使用维护良好的官方 SDK,再在业务边界增加自己的校验、日志和错误分类。
8. 浏览器与服务端的密钥边界
下面的做法不安全:
// 浏览器代码中的密钥会交付给访问页面的用户
const apiKey = "sk-...";构建工具中的“环境变量”如果被注入浏览器 bundle,也会出现在最终 JavaScript 中。变量名包含 PUBLIC、VITE_ 或类似前缀时,通常明确表示可暴露给浏览器,不能存放服务端秘密。
正确结构是:
sequenceDiagram
participant Browser as 浏览器
participant App as 自有服务端
participant Model as 模型 API
Browser->>App: 用户会话 + 业务输入
App->>App: 鉴权、限额、校验、审计
App->>Model: 服务端密钥 + 模型请求
Model-->>App: 模型响应与用量
App->>App: 校验、过滤、记录
App-->>Browser: 允许返回的结果服务端代理不只是隐藏密钥,还负责用户鉴权、预算控制、输入限制、内容策略、日志脱敏和滥用防护。
9. 何时拆成 TypeScript 与 Python 两个服务
满足以下条件之一时可以拆分:
- Python 服务必须加载只能在 Python 生态使用的模型或数据库;
- 数据计算需要独立扩缩容;
- 前端/业务 API 与模型服务由不同团队维护;
- 任务需要队列、GPU 或长时间后台执行;
- 两部分有清晰、稳定且可测试的接口。
拆分会增加:
- 两套依赖和安全更新;
- 网络调用、序列化和超时;
- 部署、日志、追踪和告警单元;
- 接口版本与兼容性管理;
- 本地开发和端到端测试成本。
如果一个 TypeScript 服务调用托管模型 API 就能完成产品,不应仅为了“AI 使用 Python”而增加 Python 服务。
10. 常见错误
10.1 把类型当作数据校验
TypeScript 类型断言和 Python 类型提示都不能证明网络响应有效。边界处需要运行时校验,关键业务结果还需要语义校验。
10.2 同时学习两套 SDK
初学者同时实现两套完全相同的客户端,会把时间用在语法和依赖差异上。先完成一个端到端流程,再用第二种语言解决第一种语言不适合的问题。
10.3 在浏览器直接调用带长期密钥的 API
用户可以检查 bundle、运行时内存和网络请求。长期服务端密钥必须保存在受控服务端或密钥管理系统中。
10.4 认为异步等于无限并发
并发请求仍消耗连接、内存、令牌预算和 API 配额。必须设置并发上限、超时、取消和针对可重试错误的退避策略。
10.5 只记录语言,不记录版本和依赖
“使用 Python”或“使用 TypeScript”不足以复现实验。还要记录运行时版本、SDK 版本、模型完整标识、请求参数、输入数据版本和 Schema 版本。
10.6 让语言边界复制业务规则
两种语言各自维护一份枚举、字段约束和错误码,容易产生不兼容。应从一份版本化 Schema 生成类型或通过契约测试保持一致。
11. 项目决策记录
在项目中保存以下内容:
# AI 应用语言决策
- 主要交付物:
- 主要运行环境:浏览器 / Node.js / Python / 其他
- 选择的语言与版本:
- 已有代码和团队能力:
- 必需的 SDK 或库:
- 运行时 Schema 方案:
- 密钥保存位置:
- 部署目标与限制:
- 第二语言的引入条件:
- 跨语言协议与版本策略:
- 放弃方案及原因:决策发生变化时,新增变更记录并写清触发条件,不直接覆盖原来的判断依据。
12. 练习
练习一:完成最小客户端
选择 TypeScript 或 Python,实现:
- 从环境变量读取密钥和模型标识;
- 设置 30 秒超时;
- 发送一个模型请求;
- 区分 HTTP 错误、网络错误和响应结构错误;
- 输出请求 ID、输入令牌、输出令牌和总令牌;
- 确认日志中没有密钥和完整敏感输入。
练习二:验证外部数据
定义如下业务结果:
{
"category": "billing",
"confidence": 0.86,
"reason": "用户询问重复扣款"
}实现运行时校验,要求:
category只能是预定义枚举;confidence是 0 到 1 的有限数字;reason是 1 到 200 个字符的非空字符串;- 多余字段按项目策略拒绝或明确忽略;
- 校验失败时不进入后续自动化。
完成标准
- 能解释语言、类型系统、运行时和 SDK 的区别;
- 能说明静态类型为什么不能替代运行时校验;
- 能画出浏览器、自有服务端和模型 API 的密钥边界;
- 能基于交付物、生态、团队和部署约束选择语言;
- 能运行一个带超时、错误处理和用量记录的最小客户端。
来源
- TypeScript Handbook(访问日期:2026-07-17)
- Node.js:Using the Fetch API(访问日期:2026-07-17)
- Python Tutorial(访问日期:2026-07-17)
- Python Packaging User Guide:Virtual Environments(访问日期:2026-07-17)
- OpenAI API:Developer quickstart(访问日期:2026-07-17)