OpenHarmony 英语学习 App 实战AI 英语学习助手的接口设计与后端架构摘要AI 能力正在成为学习类 App 的重要扩展方向。但真正落地时不能只做一个“问 AI”按钮而要围绕学习流程设计接口单词不会怎么办错题为什么错难度如何调整作文怎么批改学习报告如何生成本文以「英语视界 YingYu」项目的 Web 后端为例分享一个面向 OpenHarmony 英语学习 App 的 AI 学习助手后端架构设计。项目后端使用 Node.js Express Prisma已经预留了多类 AI 接口。相关文件web/backend/src/index.ts web/backend/src/routes/ai.ts web/backend/src/services/ai/ web/backend/src/middleware/auth.ts web/backend/prisma/schema.prisma web/frontend/src/services/api.ts一、为什么 AI 接口要拆分很多项目会把 AI 做成一个通用接口POST/ai/chat但学习类产品更适合按场景拆分单词讲解错题分析自适应难度AI 对话作文批改学习报告举一反三。这样做的好处是每个接口输入输出更清楚更容易做权限和频控更容易写前端 UI更容易替换底层模型更容易统计不同 AI 功能的使用情况。二、后端入口结构项目后端入口是index.tsimportexpressfromexpressimportcorsfromcorsimport{ authRouter }from./routes/auth.jsimport{ vocabularyRouter }from./routes/vocabulary.jsimport{ learningRouter }from./routes/learning.jsimport{ achievementRouter }from./routes/achievement.jsimport{ aiRouter }from./routes/ai.jsconstapp express() app.use(cors({origin: process.env.CORS_ORIGIN||http://localhost:3000,credentials:true})) app.use(express.json()) app.use(/api/auth, authRouter) app.use(/api/vocabulary, vocabularyRouter) app.use(/api/learning, learningRouter) app.use(/api/achievements, achievementRouter) app.use(/api/ai, aiRouter)路由按业务域拆分/api/auth登录注册/api/vocabulary词汇/api/learning学习统计/api/achievements成就/api/aiAI Agent。三、AI 路由总览routes/ai.ts中预留了多个 AI 接口router.post(/explain-word, authenticate, asyncHandler(async(req,res) {})) router.post(/explain-error, authenticate, asyncHandler(async(req,res) {})) router.post(/adaptive-difficulty, authenticate, asyncHandler(async(req,res) {})) router.post(/dialogue, authenticate, asyncHandler(async(req,res) {})) router.post(/essay-review, authenticate, asyncHandler(async(req,res) {})) router.post(/learning-report, authenticate, asyncHandler(async(req,res) {})) router.post(/generate-variations, authenticate, asyncHandler(async(req,res) {}))这些接口分别对应学习流程中的不同节点。四、所有 AI 接口都需要认证AI 接口使用authenticate中间件exportfunctionauthenticate(req: AuthRequest, res: Response, next: NextFunction) {try{constauthHeader req.headers.authorizationif(!authHeader?.startsWith(Bearer )) {returnres.status(401).json({success:false,error: {message:No token provided} }) }consttoken authHeader.split( )[1]constdecoded jwt.verify( token, process.env.JWT_SECRET||secret)asJwtPayloadreq.userId decoded.userIdreq.userRole decoded.rolenext() }catch(error) {returnres.status(401).json({success:false,error: {message:Invalid or expired token} }) } }认证的价值防止匿名滥用支持用户级学习画像支持频率限制支持未成年人保护支持学习报告按用户生成。五、单词讲解接口单词讲解接口输入word和可选contextrouter.post(/explain-word, authenticate, asyncHandler(async(req, res) {const{ word, context } req.bodyif(!word){returnres.status(400).json({ success:false, error: { message:Word is required} }) }constexplanation awaitexplainWord(word, context) res.json({ success:true, data: { explanation } }) }))对应服务返回结构包括interfaceWordExplanation{ word:stringphonetic?:stringdefinition:stringpartOfSpeech:stringusage:stringtips:stringsynonyms?:string[] antonyms?:string[] examples: Array{ sentence:stringtranslation:string} collocations:string[] level:string}这比普通翻译接口更适合学习因为它强调语境、例句、搭配和记忆技巧。六、错题分析接口错题分析需要题目、用户答案、正确答案和知识点router.post(/explain-error, authenticate, asyncHandler(async(req,res) { const { question, userAnswer, correctAnswer, topic } req.bodyif(!question||!correctAnswer) { return res.status(400).json({ success:false, error: { message: Questionandcorrect answer are required } }) } const analysis await explainError(question,userAnswer,correctAnswer,topic)res.json({ success:true, data: { analysis } }) }))这个接口适合语法练习、词汇选择题、听力理解题等场景。七、自适应难度接口自适应难度接口输入最近答题结果router.post(/adaptive-difficulty, authenticate, asyncHandler(async (req, res) {const{ recentResults } req.bodyif(!recentResults || !Array.isArray(recentResults)) {returnres.status(400).json({ success: false, error: { message: Recent resultsarrayis required } }) }constdifficulty await getAdaptiveDifficulty(recentResults) res.json({ success: true, data: { difficulty } }) }))服务层先用规则算法计算constrecent recentResults.slice(-10)constcorrectCount recent.filter(r r.correct).lengthconstaccuracy correctCount / recent.lengthconstavgResponseTime recent.reduce((sum, r) sum r.responseTime,0) / recent.length难度调整if (accuracy 0.9 avgResponseTime 3000){ newLevel Math.min(5,Math.round(avgDifficulty) 1) }else if (accuracy 0.6){ newLevel Math.max(1,Math.round(avgDifficulty) - 1) }这是一种低成本、可解释的智能能力不一定一开始就依赖大模型。八、作文批改、学习报告和对话接口项目还预留了router.post(/dialogue, authenticate, asyncHandler(async (req, res) { const { message, scenario, history } req.bodyres.json({ success:true, data: { reply:AI口语陪练功能即将上线敬请期待, suggestions: [Canyou help mewiththis?,Howmuchisthis?,Whereisthe library? ] } }) }))作文批改router.post(/essay-review, authenticate, asyncHandler(async (req, res) { const { essay, type } req.body res.json({success: true,data: {score:85,feedback: {grammar: {score:85,comments: [] },vocabulary: {score:80,comments: [] },structure: {score:90,comments: [] },content: {score:85,comments: [] } } } }) }))学习报告router.post(/learning-report, authenticate, asyncHandler(async (req, res) { res.json({success: true,data: {report: {summary:AI 学习报告生成功能即将上线,strengths: [],weaknesses: [],recommendations: [],nextGoals: [] } } }) }))这些接口目前是预留结构但已经明确了未来产品方向。九、前端 API 封装Web 前端统一封装 AI APIexportconstaiApi {explainWord:(word:string, context?:string) api.post(/ai/explain-word, { word, context }),explainError:(data: { question:stringuserAnswer?:stringcorrectAnswer:stringtopic?:string}) api.post(/ai/explain-error, data),getAdaptiveDifficulty:(recentResults:Array{ correct:booleanresponseTime:numberdifficulty:number}) api.post(/ai/adaptive-difficulty, { recentResults }),essayReview:(data: { essay:string;type?:string}) api.post(/ai/essay-review, data) }移动端后续也可以按同样结构封装 ArkTS API 客户端。十、数据库模型支撑Prisma 中定义了用户、词汇、学习统计、复习记录、成就等模型model User { idStringiddefault(uuid()) emailStringuniquepasswordStringnicknameStringgradeIntdefault(1) roleStringdefault(STUDENT) vocabularyProgress VocabularyProgress[] reviewRecords ReviewRecord[] learningStats LearningStat[] achievements UserAchievement[] }学习统计model LearningStat { id Stringiddefault(uuid()) userId String date DateTime wordsLearnedIntdefault(0)wordsReviewedIntdefault(0)correctRateFloatdefault(0)studyMinutesIntdefault(0)}这些数据可以作为 AI 学习报告和个性化推荐的输入。十一、推荐后续架构后续可以把 AI 架构设计成OpenHarmony App - API Client - Express AI Routes - AI Service Layer - Model Provider Adapter - OpenAI / 盘古 / 本地模型 / 其他服务其中AI Service Layer不直接绑定某一个模型而是输出统一格式。这样未来更换模型时不影响前端页面。十二、安全与合规建议教育类 AI 接口要特别注意所有 AI 接口必须登录限制请求频率不上传无关隐私数据作文、错题等文本要做日志脱敏未成年人场景需要更严格的内容安全AI 输出要适配年级提供“AI 解释不一定完全准确”的提示。十三、小结本文结合「英语视界 YingYu」项目梳理了 AI 英语学习助手的后端接口设计后端按 auth、vocabulary、learning、achievement、ai 拆分路由AI 接口按学习场景拆分而不是只做通用 chat所有 AI 接口都接入认证中间件单词讲解强调语境、例句、搭配和记忆技巧错题分析、自适应难度、作文批改、学习报告都有预留Prisma 数据模型为学习画像和 AI 分析提供基础后续可通过 Provider Adapter 接入不同模型。AI 学习助手真正有价值的地方不是“能聊天”而是能在学习流程中不断提供合适的帮助。把接口设计好就是迈向智能学习体验的第一步。