实战-OA学习辅助系统的【开发规范】你是不是经常听别人说“你那边有没有写好的 rest接口示例发我参考一下”我编排一个rest趣味故事—「接口小镇的两种办事规矩」看完希望你能懂了在网络世界的接口小镇里住着两位搭档前端小访客和后端大管家。小镇每天要处理用户、部门、案件各类事务过去一直用老旧规矩办事时间久了乱象丛生。两人决定重新制定一套通用规则前后一共用两天敲定了整套办事准则。第一套老规矩混合开发-传统接口风格最早小镇没有统一要求大家全凭自己习惯写办事门牌接口地址。比如要查用户信息有人挂牌子/用户/根据ID查询有人写/用户/查找还有人标/用户/检索。明明是同一件事门牌五花八门。要新增、修改、删除用户也是一样有人用 “保存”有人用 “添加”牌子越挂越多。时间一长麻烦就来了新来的工人看不懂五花八门的门牌想找对应业务得翻半天老工人离职后接手的人更是一头雾水。门牌重复、杂乱整个小镇运转越来越拖沓维护起来特别费劲。第二套新公约rest风格后来小镇居民坐下来商量定下了一套通用公约让所有门牌变得整齐统一这就是 rest 风格。第一天重整门牌告别杂乱门牌只写「办事对象」不写「做什么事」从前小镇的门牌五花八门大家总喜欢把要做的事直接写在牌子上。想查用户门牌就写/user/getById想新增用户就写/user/saveUser。每个人想法不一样有人用find、有人用select明明是同一件事门牌却各有叫法。前端每次来办事对着密密麻麻的门牌看得头晕常常找错地方后端维护这些门牌也十分头疼重复的牌子越堆越多整个小镇运转得乱糟糟。这天前端主动找到后端两人坐在一块商量整改方案。后端开口“咱们不能再这么乱下去了以后所有门牌只标注办事对象绝不写查询、新增、删除 这类动作。”前端点头“这个办法好看着也清爽。”从此全镇统一门牌上只写要办理的资源人 / 事物再也不标注查询、新增这类动作。1、门牌接口地址只写要办理的资源不体现具体操作2、资源名称统一使用复数形式。办理用户业务门牌统一写/users习惯用复数办理部门业务门牌统一写/depts办理案件业务门牌统一写/cases整改完毕后整条街道整整齐齐再也看不到杂乱的动作词汇。前端看着焕然一新的门牌心里踏实不少但随即又冒出疑问“现在同一种业务门牌都一样了光看牌子分不清我是要查信息、加内容还是删数据呀”第二天约定手势区分操作-靠「办事手势」区分具体操作第二天一早两人再次碰面专门解决 “门牌相同、分不清操作” 的难题。后端拿出提前想好的方案“门牌固定不变咱们用固定手势来区分要做的事以后全镇都按这套手势来。”前后端大家约定好四种固定手势HTTP 请求方式手势不同代表要办的事不一样比出GET手势 → 单纯查资料、查信息比出POST手势 → 新增一条数据比出PUT手势 → 修改已有数据比出DELETE手势 → 删除数据规则落地后一切豁然开朗。同样站在/users门牌前前端比出 GET 手势后端就知道对方要查询用户比出 POST 手势就是要新增用户比出 PUT 手势代表修改用户信息比出 DELETE 手势便是要删除用户。一套组合规则正式成型门牌定位办事对象手势决定具体操作也就是大家口中的rest风格。闲聊时后端特意叮嘱前端“这套规则只是咱们圈子里大家商量好的约定不是硬性律法。就算不按这套来事情也能办成只是会变回从前杂乱的样子。”他又分享了职场经验“以后如果去到别的地方做事先看看当地原本用的是什么规矩。人家还用老门牌写法你就跟着沿用不要贸然改动等你待得久了、有话语权了再提议统一成这套简洁的新规则后续维护会省心很多。”约定好所以东西就要形成一个【接口文档】就4个东西1、请求路径 2、请求方式 3、请求参数 4、响应数据同时也要告知对方自己使用的服务器是什么前端说我用的是Ningx本地的一种软件服务器Nginx 前端专用的本地软件服务器作用放页面、原型、HTML、图片、JS专门给浏览器访问用后端说我用的是Tomcat本地的一种软件服务器Tomcat 后端专用的本地软件服务器作用运行 Java 接口、运行 Controller专门处理增删改查、业务逻辑小镇居民的共识与提醒这套规则只是大家商量好的约定不是硬性法律。就算不遵守业务也能正常办理只是会回到门牌杂乱的老样子。如果你是新来的工作人员镇上已经在用老门牌你就跟着用老规矩镇上已经推行新公约你就遵守新风格。别一上来就擅自改规矩。等你熟悉环境、有话语权之后再提议全镇统一标准。故事小结至此靠着这两天定下的准则前端办事一目了然后端维护轻松高效接口小镇从此秩序井然这套简洁规范的办事方式也慢慢被更多人沿用下来。老规矩门牌写满操作看着直白但是杂乱难管理。新公约rset门牌定位资源手势决定操作简洁、规范、好协作现在新开发的项目基本都会优先使用这套方式。小知识装一个Axure插件方便直接看.html文件。实战-OA学习辅助系统的【环境配置】你是不是经常听别人说“新项目怎么快速搭环境、接口没有页面怎么自测”开发趣味故事 —「开发小镇的协作建站记」在代码世界里有一座热闹的开发小镇镇上分工明确前端居民负责搭建展示门面后端居民处理核心事务大家依靠各类工具伙伴协作干活。今天小镇要新建一座「清单管理服务站」前后居民要联手完成搭建、测试与运行整个过程分成两大阶段推进。第一幕请来专属质检员学会核验接口服务站还在动工后端工匠们已经率先把内部办事规则接口全部设计好了可前端的门面建筑还没完工。没有对外窗口工匠们没法让访客模拟来访检验规则能不能正常运转。这时小镇的专职质检员 API Fox登场了和老搭档Postman一样它精通模拟访客、核验接口的本领而且上手更简单、功能更全面。www.apifox.comApifox - API 文档、调试、Mock、测试一体化协作平台。拥有接口文档管理、接口调试、Mock、自动化测试等功能接口开发、测试、联调效率提升 10 倍。最好用的接口文档管理工具接口自动化测试工具。https://apifox.com/API Fox 有两种常驻方式既能在网页临时办公也能把办公软件装在本地电脑。居民们选择下载客户端安装过程十分简单一路点击下一步就能完成。打开软件后需要扫码登录登录后还有个贴心能力哪怕换了新电脑之前记录的所有接口资料都能自动同步不会丢失。为了方便理解我自己在我任意项目中随意写了一个。在src中找到org.example.wslantsringboot包在里面创建了一个controller的包又在里面创建了一个TestController.java的类文件。写了一下一段小代码用于给APIfox这个工具来测试发送请求。这就是4要素1、请求路径 2、请求方式 3、请求参数 4、响应数据正式开始核验工作啦质检员点开界面上的加号选择「快捷接待」模式。首先要填写来访地址 URL和浏览器访问地址写法完全一致接着选定通行方式日常接待只用到四种核心方式GET、POST、PUT、DELETE其余方式基本用不上。如果访客需要携带资料就在参数区填写本次暂无额外资料便留空。全部信息填好后点击「发送」模拟访客到访。界面上方会清晰展示来访路径、通行方式和携带资料下方的响应区就会返回接口处理后的结果。这里还有一个小知识点普通浏览器这位老伙计只能简单处理 GET 类型的来访而 API Fox 可以自由切换四种通行方式完美适配当下主流的接口规则。最后大家约定后续还要把批量接口资料导入 API Fox统一进行核验管理。而我们制定这套统一的接口通行规则RESTful 风格可不只是看着整齐优雅最关键的是后续服务站迭代、维护时所有人都能快速看懂规则大幅减少返工麻烦。第二幕搭建后端主建筑筑牢服务根基核验工具准备就绪接下来正式动工搭建服务站的核心主楼 —— 后端项目全镇后续的后端建筑都会统一采用SpringBoot框架来建造。工匠们选用 IDEA 里的Spring 初始化器来快速搭建工程效率最高。首先给新建筑取名「清单管理系统」选定 Maven 作为建筑搭建工具修改项目标识、精简包路径确定使用 JDK21 作为运行环境。随后挑选两位得力助手入驻工程第一位是Spring Web它是对外接待的主力专门负责接收外界请求、运转接口第二位是Lombok当然还有其它依赖它们是贴心的文书助手不用人工重复编写实体类的取值、赋值方法依靠Data注解就能自动生成大大简化书写工作。勾选完依赖项目正式创建完成。工匠们清理掉多余杂物只保留两大核心部分src源码目录存放所有建筑代码、pom.xml总配置文件。大家仔细研读pom.xml这份建筑总章程整座建筑依托的 SpringBoot 父框架版本为 3.2.4文件里的java.version是版本标记它会沿用父框架的版本规则同时将运行环境覆盖为我们选定的 JDK21写法灵活且统一章程里记录了 Web、Lombok、单元测试三类内置工具配套了打包规则并且特意设置建筑打包上线时排除 Lombok 助手避免出现运行问题。看完配置再梳理建筑内部结构项目自带启动总开关启动类点击它就能整座建筑通电运行。由于还没讲解完整的分层架构大家先简化布局新建了pojo 房间专门用来存放描述事物信息的实体类controller、service等功能房间暂时延后规划。先设置数据库端口8089你自己设置你的然后输入一段小代码并启动他现在我们用APIfox工具看看这个接口通没全部布置完毕后工匠们按下启动开关服务站成功通电运行默认开放 8089出入口。能正常启动就代表后端主楼环境搭建圆满完成。按照最初规划后端主楼完工后暂且告一段落。等后续环节再启用提前准备好的前端门面工程让前后建筑联通开展整体联调。至此从接口测试工具准备到后端项目完整搭建整座「清单管理服务站」的前期环境就全部准备好了。