Spring 项目 实战基础 10

项目10“彩云之南-文旅驿站”项目第三方API接入实施01【学前导读】【学前导读】本项目介绍第三方API接口的基本概念、原理和应用；通过具体实例，展示如何在“彩云之南-文旅驿站”项目中使用第三方API接口，如阿里云通义千问大模型API，实现智能问答功能；讲解第三方API的选择、集成和优化方法。02【学习目标】【学习目标】理解第三方外部API接口的基本概念、原理和作用；掌握调用第三方API接口的方法，能够根据API文档构建请求和处理响应数据；具备评估第三方API接口优劣的能力，能够为项目选择合适的API接口；根据实际项目需求，对第三方API接口进行优化整合。03【课程思政】【课程思政】尊重知识产权，培养学生尊重知识创造的价值观；通过API应用案例，激发创新思维；讲解API安全漏洞及防范措施，培养网络安全的警惕性和责任感；要求在API调用中如实提供信息，坚守诚信原则；鼓励思考如何运用API为社会公益事业服务，培养人文情怀和社会担当。第三方外部API接口为开发者提供了丰富的功能和数据来源，通过合理地集成这些API，可以快速增强应用的能力，提升用户体验。任务10.1第三方API接口知识的学习任务10.1第三方API接口知识的学习第三方外部API‌是指由第三方开发者或公司提供的公开接口，允许其他开发者或公司通过这些接口访问和使用其提供的功能或服务。这些接口通常用于不同应用程序之间的通信，将具体的实现过程隐藏起来，只暴露必要的部分给开发者使用。‌10.1.1接口定义与接口契约10.1.1接口定义与接口契约第三方接口是基于一种事先定义好的契约来工作的。这个契约规定了接口的功能、输入参数的格式和要求、输出数据的格式以及调用方式等诸多细节。例如，一个地图导航的第三方接口，契约中会明确规定如查询地址功能需要传入地址的名称（输入参数），输出类型、具体数据的来源，信息的数据格式（可能是JSON或XML），并且会规定调用该功能的HTTP请求方法（如GET或POST）以及请求的URL结构。百度地图契约参数表如图10-1所示。图10-1百度地图契约参数表10.1.2网络通信协议10.1.2网络通信协议HTTP/HTTPS协议细节：HTTP和HTTPS是Web第三方接口通信的基石。HTTP（超文本传输协议）是一种无状态的协议，这意味着每个请求都是独立的，服务器不会记住之前的请求状态。HTTPS（超文本传输安全协议）则是在HTTP的基础上增加了SSL/TLS加密层，用于保证数据传输的安全性。在发送请求时，Web应用会先与第三方接口服务器通过TCP三次握手建立连接。以查询股票价格的第三方接口为例，当浏览器（作为Web应用的客户端代理）向接口服务器（假设地址为/docs/api/id/21）发送请求时，它会先进行SSL/TLS握手，协商加密算法等参数，然后再发送实际的HTTP请求。HTTPS网络传输协议过程如图10-2所示。10.1.2网络通信协议图10-2HTTPS网络传输协议示意图图10-2HTTPS网络传输协议示意图10.1.3请求方法多样化GET方法GET方法主要用于从服务器获取资源。它的参数通常会附加在URL后面，如查询未来7天的天气信息的接口请求:/api?unescape=1&version=v93&appid=25573829&appsecret=PIv0ADM2&ext=&cityid=18，其中，unescape代表的是否转义中文，1代表中文；version=v93是这个接口的版本固定写法；appid为用户在网站上的ID；cityid代表要查询的城市ID。这种方式方便快捷，但由于参数暴露在URL中，对于敏感信息不太适合。HTTP定义了多种请求方法。在第三方接口中比较常用的是GET和POST。POST方法POST方法用于向服务器提交数据，数据通常放在请求体中。比如用户注册接口，Web应用会将用户填写的注册信息（如用户名、密码、邮箱等）以POST方式发送到接口服务器，这样可以更好地保护数据隐私。10.1.4请求处理流程解析10.1.4请求处理流程解析在请求解析阶段，当第三方接口服务器收到请求后，首先会对请求进行解析。它会根据请求的协议（HTTP/HTTPS）规范来读取请求头和请求体。请求头该部分会检查如Content-Type（用于指定请求体的数据类型，如application/json表示JSON格式数据）、User-Agent（可以识别请求客户端的信息）等重要字段。如果请求头不符合接口要求，可能会导致请求被拒绝。例如，若接口要求请求体数据为JSON格式，但Content-Type字段被设置为text/plain，接口服务器可能无法正确解析数据。请求体该部分会根据Content-Type和请求方法进行不同的处理。在GET请求中，请求体通常为空，主要处理URL中的参数；在POST请求中，会根据Content-Type来解析请求体中的数据。如果是JSON格式，会将其解析为内部的数据结构以便后续处理。业务逻辑执行在解析完请求后，接口服务器会根据请求的内容执行相应的业务逻辑。假设是一个在线翻译第三方接口，当收到翻译请求后，服务器会调用内部的翻译引擎。这个翻译引擎可能会有自己的词库、语法规则库等，它会根据请求中的源语言和目标语言参数，以及待翻译的文本内容，在词库和规则库中查找匹配项，通过复杂的算法生成翻译结果。在执行完业务逻辑后，如果需要返回数据，接口服务器会从数据库或其他数据源获取相关数据，并按照预定的数据格式进行组装。对于一个电商商品信息接口，服务器可能会从商品数据库中查询商品的名称、价格、库存、描述等信息。如果接口定义的输出格式是JSON，它会将这些数据组装成一个JSON对象，如：{"product_name":"SmartphoneX","price":599.99,"stock":100,"description":"Ahigh-performancesmartphonewithadvancedfeatures."}10.1.5响应返回状态码状态码含义与应用接口服务器返回的响应状态码对于Web应用理解请求结果非常重要。状态码200：请求成功，并且返回了正确的数据。例如，当Web应用请求获取社交媒体的用户动态信息，收到200状态码时，表示成功获取到了动态列表。状态码400：客户端请求有错误，通常是因为请求参数不符合要求。比如，一个图像识别接口要求上传的图像格式为JPEG，但Web应用上传了PNG格式的图像，接口服务器可能会返回400状态码。状态码401：未授权，即Web应用没有提供正确的认证信息（如API密钥或用户名/密码）来访问接口。状态码404：请求的资源不存在，可能是因为接口的URL路径错误或者请求的功能不存在。响应头的作用响应头包含了关于响应的各种附加信息。例如，Content-Type字段会告诉Web应用返回数据的数据类型，这有助于Web应用正确地解析响应体中的数据。如果Content-Type是application/json，Web应用就知道要用JSON解析器来处理响应体；如果是text/html，可能是返回了一个完整的HTML页面，用于在浏览器中显示。还有如Content-Length字段会告诉Web应用响应体的长度，这对于接收数据的完整性检查等有帮助。响应体的内容传输响应体是真正包含数据或执行结果的部分。它的内容会根据之前定义的契约和业务逻辑进行生成。以获取音乐播放列表的接口为例，响应体可能是一个包含多首歌曲信息（如歌曲名称、歌手、时长等）的JSON数组，Web应用在收到响应后，可以根据这些信息在自己的音乐播放界面上展示播放列表。10.1.6数据格式与交互细节JSON格式JSON是一种非常流行的数据格式，它的结构简单且易于解析。JSON对象是由键-值对组成的无序集合，键是字符串，值可以是字符串、数字、布尔值、对象、数组或者null。例如，一个包含用户订单信息的JSON对象可能如下：[{"product_id":"P001","product_name":"BookA","quantity":2},{"product_id":"P002","product_name":"PenB","quantity":1}]这里“products”键的值是一个JSON数组，数组中的每个元素又是一个JSON对象，用于表示订单中的不同产品信息。这种嵌套结构可以很好地表示复杂的数据关系。XML格式XML具有很强的可扩展性和自描述性，它通过标签来定义元素，每个XML元素都可以有属性。例如，同样是用户订单信息，用XML表示代码如下：<orderorder_id="12345"><customer_name>zhangsan</customer_name><products><productproduct_id="P001"><product_name>水浒传</product_name><quantity>2</quantity></product></products>"product_id":"P002","product_name":"PenB","quantity":1}]这里“products”键的值是一个JSON数组，数组中的每个元素又是一个JSON对象，用于表示订单中的不同产品信息。这种嵌套结构可以很好地表示复杂的数据关系。10.1.7常用的第三方API接口提供商选择与评估10.1.7常用的第三方API接口提供商选择与评估第三方外部API接口提供商为开发者提供了丰富的功能和服务。国内常用的第三方外部API接口提供商有很多，包括提供地图、支付、社交媒体、短信、人工智能等服务的公司，如表10-1所示。表10-1国内主要的API提供商及其服务在软件开发的后期阶段，第三方API发挥着关键作用，显著提升开发效率和应用功能性。首先，第三方API能够快速扩展应用功能，例如，通过集成支付网关API实现在线支付，无须从头开发，大大节省时间和资源。其次，这些API提供了可靠性和安全性，第三方服务商通常拥有专业知识和丰富经验，以维护和更新其服务，从而降低开发团队的维护成本。10.2.1需求分析和API选择首先要明确应用程序的需求，确定需要哪些具体功能，例如支付、地图服务、身份验证等。然后选择适合这些需求的第三方API，还要从API的功能、稳定性、安全性、成本和技术支持等方面考虑。10.2.2注册和获取访问权限访问大多数第三方API需要注册开发者账号。完成注册后，用户通常会得到一个API密钥或访问令牌，用于验证和授权API请求。10.2.3阅读和理解API文档详细阅读API提供的文档，这是了解如何正确使用API的重要步骤。文档通常包含API的功能介绍、请求和响应格式、错误代码和示例代码等。10.2.4环境配置如果API需要特定的环境配置，例如安装特定的开发库或设置网络请求工具，确保按要求进行配置。某些编程语言或框架可能需要安装额外的库或插件。10.2.5编写代码以调用API编写代码调用API并处理响应的基本步骤通常包括：（4）处理响应：接收并解析API响应，通常是JSON或XML格式，处理返回的数据或错误。（1）设置请求URL：根据API文档，构建请求的URL，包括必要的路径和查询参数。（3）发送请求：使用合适的HTTP方法（如GET、POST、PUT、DELETE）发送请求。（2）添加请求头和参数：配置请求头（如API密钥、内容类型）和请求参数（如查询参数、请求体）。10.2.6测试和调试集成API的过程应进行充分的测试和调试，以确保功能正确实现；处理好可能出现的错误和异常情况，确保应用在面对各种情况时能够正常工作。10.2.7监控和维护231API集成后应设置监控以确保其稳定运行；定期检查API提供者发布的更新或变更，及时调整代码以保持兼容性和安全性。任务10.3“彩云之南-文旅驿站”项目接入第三方API的实现下面以“彩云之南-文旅驿站”接入阿里通义千问为例讲解。10.3.1接入阿里通义千问的意义通义千问大模型是阿里云推出的一个超大规模的语言模型，具有强大的归纳和理解能力，可以处理各种自然语言处理任务，包括但不限于文本分类、文本生成、情感分析等。此模型能够极大地提高自然语言处理的效率和准确性，给用户提供了一种新的、简便的工具。图10-3阿里通义千问大模型首页“彩云之南-文旅驿站”旅游项目中融入阿里通义千问，能够为整个项目带来全方位的升级与优化，为游客和项目运营方创造显著价值。智能交互升级通义千问强大的自然语言处理能力，可为文旅驿站项目赋能，打造智能客服。游客咨询云南旅游相关问题时，无论是景点特色、游玩路线规划，还是当地美食推荐，智能客服都能基于通义千问快速理解游客意图，并给出精准、详细且人性化的回答。例如游客询问“大理洱海周边有哪些适合看日出的地方？”通义千问能迅速检索相关信息，为游客提供诸如龙龛码头、磻溪村等多个地点，并附上最佳观赏时间和交通指南，让游客咨询体验更加流畅高效。内容创作革新项目方在制作云南旅游攻略、景点介绍文案、宣传推广语时，借助通义千问能快速生成初稿。以撰写一篇“关于香格里拉普达措国家公园的介绍”文案为例，通义千问可结合公园的生态环境、特色景观、游玩项目等信息，生成生动形象、富有感染力的文案，再由人工进行优化完善，大大提高内容创作效率和质量，丰富文旅驿站项目的内容生态。数据分析赋能项目能精准分析游客需求和兴趣点，从而优化旅游产品推荐。比如发现大量游客对云南少数民族文化体验感兴趣，项目方就可以针对性地推出更多民族文化体验活动，并在文旅驿站平台重点推荐，提升游客参与度和满意度，实现项目的精准运营。10.3.2接入的具体步骤（1）登录阿里云官网，开通API-KEY，如图10-4所示。（2）创建API-KEY，如图10-5所示。图10-4阿里通义千问大模型开通API-KEY10.3.2接入的具体步骤（3）导入第三方需要的依赖。<!--阿里巴巴大模型--><!--/artifact/com.alibaba/dashscope-sdk-java--><dependency><groupId>com.alibaba</groupId><artifactId>dashscope-sdk-java</artifactId><exclusions><exclusion><groupId>org.slf4j</groupId><artifactId>slf4j-simple</artifactId></exclusion></exclusions><version>2.8.3</version></dependency>图10-5阿里通义千问大模型创建API-KEY10.3.2接入的具体步骤（4）后端SpringBoot中编写AiController层。这里controller层可以将前端的请求数据传入给API中的参数，然后根据参数内容调用大模型进行计算，再回复给用户对应的应答数据：packagecom.example.controller;importcom.alibaba.dashscope.aigc.generation.Generation;importcom.alibaba.dashscope.aigc.generation.GenerationParam;importcom.alibaba.dashscope.aigc.generation.GenerationResult;importmon.Message;importmon.Role;importcom.alibaba.dashscope.exception.InputRequiredException;importcom.alibaba.dashscope.exception.NoApiKeyException;importmon.Result;importjakarta.annotation.Resource;10.3.2接入的具体步骤importorg.springframework.beans.factory.annotation.Value;importorg.springframework.web.bind.annotation.PostMapping;importorg.springframework.web.bind.annotation.RequestBody;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;importjava.util.Arrays;@RestController@RequestMapping("/getAi")publicclassAiController{

@Value("${ai-api-key}")//填写自己在阿里云平台申请的key

privateStringapiKey;

@Resource10.3.2接入的具体步骤privateGenerationgeneration;/****@paramcontent用于输入文本内容*/@PostMapping("/aliTyqw")publicResultsend(@RequestBodyStringcontent)throwsNoApiKeyException,InputRequiredException{//用户与模型的对话历史。list中的每个元素形式为{“role”:角色,“content”:内容}。MessageuserMessage=Message.builder().role(Role.USER.getValue()).content(content).build();GenerationParamparam=GenerationParam.builder()//指定用于对话的通义千问模型名.model("qwen-turbo").messages(Arrays.asList(userMessage))

10.3.2接入的具体步骤.resultFormat(GenerationParam.ResultFormat.MESSAGE)//生成过程中核采样方法概率阈值，例如，取值为0.8时，仅保留概率加起//来大于等于0.8的最可能token的最小集合作为候选集。//取值范围为(0,1.0)，取值越大，生成的随机性越高；取值越低，生成的确//定性越高。.topP(0.8)//阿里云控制台DASHSCOPE获取的api-key.apiKey(apiKey)//启用互联网搜索，模型会将搜索结果作为文本生成过程中的参考信息，但//模型会基于其内部逻辑“自行判断”是否使用互联网搜索结果。.enableSearch(true).build();GenerationResultgenerationResult=generation.call(param);//System.out.println(generationResult.getOutput().getChoices().get(0).getMessage().getContent());returnResult.success(generationResult.getOutput().getChoices().get(0).getMessage().getContent());}}以上代码的主要作用是使用SpringBoot中的AiController来进行控制页面发过来的数据，然后通过这些数据传递给阿里云通义千问大模型进行计算。这里必须要注意的是在代码中使用API-KEY。等待大模型计算完毕就可以把最后的问答结果返回给页面展示。10.3.2接入的具体步骤（5）前端Vue页面中编写提交数据的组件。<template><divclass="chat-container"><!--聊天消息区域--><divclass="chat-body"ref="chatBody"><divv-for="(message,index)inmessages":key="index":class="['message',message.isAI?'ai':'user']"><divclass="message-content"><spanclass="message-text">{{message.text}}</span></div></div></div><!--输入框和发送按钮--><divclass="chat-footer"><el-inputv-model="messageInput"

10.3.2接入的具体步骤placeholder="请输入消息..."@keyup.enter="sendMessage"class="chat-input"/><el-button@click="sendMessage"type="primary"class="send-btn">发送</el-button></div></div></template><scriptsetup>import{ref}from'vue';import{ElInput,ElButton,ElNotification}from'element-plus';importrequestfrom"@/utils/request";//定义响应式变量constmessageInput=ref('');constmessages=ref([{text:'您好，欢迎使用“彩云之南-文旅驿站”AI助手！',isAI:true},]);10.3.2接入的具体步骤//发送消息函数constsendMessage=()=>{constuserMessage=messageInput.value.trim();if(userMessage){//用户发送的消息messages.value.push({text:userMessage,isAI:false});//保留输入框的内容后再清空constcontent=messageInput.value;messageInput.value='';//清空输入框//调用后端API获取AI回复request.post('/getAi/aliTyqw',{content}).then(res=>{if(res.code==='200'){//从返回的AI回复中提取出content字段constaiReply=res.data;//将AI回复添加到消息列表messages.value.push({text:aiReply,isAI:true});10.3.2接入的具体步骤scrollToBottom();//滚动到底部}else{ElNotification.error(res.msg);//错误通知}}).catch(error=>{ElNotification.error("请求失败，请稍后再试！");});scrollToBottom();//滚动到底部}};//滚动到底部constscrollToBottom=()=>{constchatBody=document.querySelector('.chat-body');chatBody.scrollTop=chatBody.scrollHeight;};</script><stylescoped>10.3.2接入的具体步骤.chat-container{display:flex;flex-direction:column;height:90vh;/*高度设为90vh，确保不会过高*/width:60%;/*宽度调整为60%*/

margin:0auto;/*居中显示*/border-radius:20px;background-color:#ffffff;/*背景改为白色*/box-shadow:015px50pxrgba(0,0,0,0.1);/*更强的阴影效果*/overflow:hidden;}.chat-body{flex:1;overflow-y:auto;padding:20px;background-color:#f9f9f9;/*浅灰背景，更干净清爽*/}10.3.2接入的具体步骤border-radius:20px;box-shadow:inset02px6pxrgba(0,0,0,0.1);/*内部阴影，增加立体感*/}.message{margin-bottom:18px;padding:16px;border-radius:25px;font-size:16px;line-height:1.5;max-width:80%;transition:transform0.2sease,opacity0.3sease;/*平滑动画*/word-wrap:break-word;.message:hover{transform:translateY(-3px);/*悬停时微微上浮*/opacity:0.95;}.user{10.3.2接入的具体步骤background:linear-gradient(145deg,#00aaff,#0077cc);/*动态蓝色渐变*/color:white;align-self:flex-end;border-radius:25px25px025px;box-shadow:04px15pxrgba(0,170,255,0.3);/*高光效果*/}.ai{background:#dbdee0;/*纯白背景*/color:#333333;/*深色字体*/align-self:flex-start;border-radius:25px25px25px0;max-width:75%;box-shadow:04px15pxrgba(0,0,0,0.1);/*微光效果*/}.message-content{font-size:14px;word-wrap:break-word;}10.3.2接入的具体步骤.chat-footer{padding:12px20px;display:flex;align-items:center;background-color:#ffffff;/*白色背景*/border-top:1pxsolid#ddd;/*灰色边框*/border-bottom-left-radius:20px;border-bottom-right-radius:20px;}.chat-input{flex:1;padding:14px20px;border-radius:40px;font-size:16px;background-color:#f5f5f5;/*浅灰背景*/border:1pxsolid#ddd;/*灰色边框*/color:#333;transition:all0.2sease;}10.3.2接入的具体步骤.chat-input:focus{outline:none;border-color:#00aaff;/*聚焦时的边框颜色*/box-shadow:0015pxrgba(0,170,255,0.5);/*聚焦时的光晕*/}.send-btn{padding:14px24px;margin-left:15px;background-color:#00aaff;color:white;border:none;border-radius:40px;cursor:pointer;transition:all0.3sease;font-size:16px;}.send-btn:hover{10.3.2接入的具体步骤.send-bt