173 lines
14 KiB
Markdown
173 lines
14 KiB
Markdown
# 1. 实践目的
|
||
|
||
## 1.1 项目概述与个人贡献
|
||
|
||
### 1.1.1 项目概述
|
||
|
||
本项目旨在解决传统环保监督渠道反馈不畅、处理流程不透明、以及公众参与度不高等痛点，开发一个高效、透明的**环保公众监督平台**。作为《东软环保应急》系统的重要子模块，它不仅是技术上的实现，更是业务流程上的一次重要创新。
|
||
|
||
系统的核心目标是打通从"问题发现"到"问题解决"的全链路。它通过提供便捷的移动端/网页端入口，鼓励公众随时随地上传图文并茂的环境问题反馈。系统接收到反馈后，将**自动触发一系列内部流程**：首先通过AI服务进行初步的智能分类与严重性评估；随后，经由主管人员审核确认后，反馈将**自动转化为一个结构化的处理任务**；最后，系统基于**智能分配算法**，综合考量网格员的实时位置、当前负载等因素，将任务精准派发给最优的执行者。整个过程的状态（待处理、执行中、已完成、已归档）对管理者和反馈者全程可见，极大地提升了环保工作的透明度与处理效率。
|
||
|
||
### 1.1.2 个人贡献
|
||
|
||
在本次实践中，本人担任**核心的系统设计与后端开发角色**，全面负责了从技术选型到项目落地的完整技术实现。我的工作不仅是代码的编写者，更是整个后端架构的**设计者**和**构建者**。具体贡献如下：
|
||
|
||
* **架构设计与技术决策**：在项目初期，我主导了技术栈的选型，力主采用`Spring Boot` + `Vue.js`的前后端分离架构，以应对未来快速迭代和功能扩展的需求。同时，我独立设计了后端**Controller-Service-Repository**的三层应用架构，并规划了项目的整体模块（如安全、事件、仓储等），为整个项目的稳固开发奠定了基础。
|
||
|
||
* **核心难题攻关**：面对"所有数据需以文件形式存储"这一核心且棘手的约束，我没有采取简单的文件读写，而是独立设计并实现了一套**模拟JPA规范的泛型JSON仓储层**。这个创新方案不仅完美地解决了数据持久化问题，其遵循的"依赖倒置原则"也使得代码高度解耦，极大地提升了系统的可维护性和可测试性，是本次项目中技术含量最高的突破之一。
|
||
|
||
* **全栈功能实现**：我负责了全部后端模块的编码实现，包括但不限于基于`Spring Security`和`JWT`的**用户认证与授权系统**、**任务全生命周期的状态机管理**、以及基于**A*算法的智能任务分配模型**等。此外，我也参与了部分前端页面的开发，并利用`Swagger`和`Postman`完成了所有API的设计、文档化与测试工作，确保了前后端的顺畅联调。
|
||
|
||
## 1.2 个人能力培养
|
||
|
||
通过本次实践，本人将软件工程理论与开发实践深度结合，在设计与开发复杂问题的解决方案方面获得了显著提升。
|
||
|
||
* **软件工程全周期掌控能力**：通过完整地参与从需求分析、系统设计、编码实现到测试部署的全过程，深刻掌握了现代软件开发的生命周期要素和方法。能够运用面向对象的思想，通过UML对系统进行建模，合理地划分模块，确保了系统设计的高内聚、低耦合。
|
||
|
||
* **复杂问题解决方案的设计与创新能力**：
|
||
* 面对"数据以文件格式保存"的核心约束，没有采用简单的序列化读写，而是创新性地设计并实现了一套**基于JSON的泛型仓储层（Repository Pattern）**。该方案遵循了依赖倒置原则，不仅满足了功能要求，更保证了代码的可维护性与未来向数据库迁移的可行性。
|
||
* 针对任务分配场景，设计了**基于多维因素（地理位置、负载）的智能调度算法**，并集成了**A*寻路算法**进行路径规划，展现了运用科学算法解决实际工程问题的能力。
|
||
* 在系统中有效运用了**事件驱动模型**，将耗时的AI分析流程解耦为异步操作，提升了系统的响应速度和健壮性。
|
||
|
||
* **技术沟通与文档化能力**：能够通过撰写系统设计方案、绘制UML图表等方式，系统、清晰地阐述项目的技术架构与实现细节，并具备良好的口头技术交流能力。
|
||
|
||
# 2. 相关技术基础
|
||
|
||
本项目综合运用了业界主流的开发技术与环境，构建了一个现代化Web应用。整体技术体系由以下五部分构成：
|
||
|
||
* **理论基础**：遵循**面向对象编程(OOP)**、**SOLID设计原则(尤其是DIP)**、**MVC分层架构**及**RESTful API**设计规范。
|
||
* **后端技术栈**：以 **`Spring Boot 3`** 为核心，整合 **`Spring Security`** 与 **`JWT`** 进行安全控制，并创新性地设计了**自定义的泛型JSON仓储层**作为持久化方案。
|
||
* **前端技术栈**：采用 **`Vue 3`** 作为核心框架，配合 **`Vite`** 进行构建，使用 **`Pinia`** 进行状态管理，**`Element Plus`** 作为UI组件库，并对 **`Axios`** 进行了封装。
|
||
* **测试技术**：后端采用 **`JUnit 5`** 和 **`Mockito`** 进行单元/集成测试；接口层使用 **`Swagger UI`** 和 **`Postman`** 进行测试与调试。
|
||
* **开发工具与环境**：使用 **`IntelliJ IDEA`** 和 **`VS Code`** 作为主力IDE，通过 **`Maven`** 和 **`npm`** 管理项目，并利用 **`Git`** 进行版本控制。
|
||
|
||
以下是各部分的详细介绍。
|
||
|
||
## 2.1 理论基础
|
||
|
||
项目的架构和代码设计遵循了下述成熟的软件工程理论，以确保系统的可维护性和扩展性。
|
||
|
||
* **面向对象编程 (OOP):**
|
||
项目的核心编程思想，其封装、继承、多态特性在后端代码设计中得到了深入应用。
|
||
* **封装 (Encapsulation):** 核心业务实体（如`User`, `Task`）被抽象为Java类，其属性私有化，仅通过公共方法暴露，保证了对象状态的完整性。
|
||
* **继承 (Inheritance) 与多态 (Polymorphism):** 在自定义的JSON仓储层设计中，通过定义泛型接口`JsonRepository<T, ID>`和实现该接口的泛型基类`JsonRepositoryImpl<T, ID>`，使得具体的实体仓储（如`JsonUserRepositoryImpl`）能自动获得通用的数据操作能力。业务逻辑层依赖于抽象接口而非具体实现，实现了"面向接口编程"，提高了代码的灵活性。
|
||
|
||
* **SOLID设计原则，尤其是依赖倒置原则 (DIP):**
|
||
项目架构遵循SOLID原则，特别是依赖倒置原则，即"高层模块不应依赖于低层模块，两者都应依赖于抽象"。
|
||
* **实践应用:** `Service`层（高层模块）依赖的是`UserRepository`等抽象接口，而不是`JsonRepositoryImpl`这样的具体实现（低层模块）。这种设计倒置了传统的依赖关系，极大提升了系统的可替换性和可测试性。未来更换数据源或进行单元测试时，只需更换实现或模拟接口，上层代码无需改动。
|
||
|
||
* **模型-视图-控制器 (MVC) 分层架构:**
|
||
项目遵循MVC分层思想，并扩展为更精细的四层架构：Controller -> Service -> Repository -> Entity。
|
||
* **Controller (控制器层):** 作为HTTP请求的入口，负责解析请求参数，调用`Service`层执行业务逻辑，并返回响应。
|
||
* **Service (业务逻辑层):** 包含所有业务规则和处理流程，通过依赖注入（DI）调用`Repository`层。
|
||
* **Repository (数据访问层):** 数据持久化的抽象，负责与数据源（本项目中为JSON文件）交互，实现业务与数据的解耦。
|
||
* **Entity/DTO (模型层):** POJO对象，`Entity`映射数据存储结构，`DTO`（Data Transfer Object）用于各层之间的数据传输，避免持久化实体直接暴露给外部。
|
||
|
||
* **RESTful API 设计原则:**
|
||
前后端通信完全基于RESTful风格的API进行。
|
||
* **统一接口 (Uniform Interface):** 使用HTTP标准方法（`GET`, `POST`, `PUT`, `DELETE`）表达对资源的操作。
|
||
* **无状态 (Stateless):** 服务端不保存客户端会话状态，每次请求都包含所有必要信息（如JWT），提高了系统的可伸缩性。
|
||
* **资源导向 (Resource-Oriented):** API围绕"资源"展开，使用名词（如`/api/users`）标识资源，而非动词。
|
||
|
||
## 2.2 后端技术栈
|
||
|
||
* **核心框架 - `Spring Boot 3.x`:**
|
||
作为后端应用基石，它通过自动配置、起步依赖和内嵌服务器等特性，极大地简化了Spring应用的开发、配置和部署。其强大的生态整合能力，使得集成`Spring Security`、`Lombok`、`Swagger`等第三方库变得非常简单。
|
||
|
||
* **安全框架 - `Spring Security 6.x` & `JWT`:**
|
||
采用`Spring Security`结合`JSON Web Tokens (JWT)`，构建无状态的认证与授权体系。
|
||
* **`Spring Security` Filter链:** 自定义`JwtAuthenticationFilter`过滤器，用于在每个请求中校验JWT并设置安全上下文。
|
||
* **声明式权限控制:** 使用`@PreAuthorize`注解对Service方法进行方法级别的权限声明，实现了安全逻辑与业务逻辑的解耦。
|
||
* **无状态会话 (Stateless Session):** 配置会话管理策略为`STATELESS`，使后端服务成为真正的无状态服务，提升了系统的可伸缩性。
|
||
|
||
* **持久化方案 - 自定义泛型JSON仓储层:**
|
||
为满足"数据存储在JSON文件中"的需求，设计并实现了一套模拟`Spring Data JPA`接口规范的、可复用的泛型JSON仓储层。
|
||
* **`JsonStorageService`:** 将所有文件I/O操作封装在此服务中，并使用`synchronized`块确保并发写操作的线程安全。
|
||
* **`JsonRepositoryImpl<T, ID>`:** 泛型基类，实现了通用的CRUD功能，具体的实体仓储通过继承该类来复用代码。
|
||
* 该方案遵循**依赖倒置原则**，业务层仅依赖抽象接口，为未来平滑迁移持久化方案提供了便利。
|
||
|
||
* **数据校验 - `Jakarta Bean Validation` (`Hibernate Validator`):**
|
||
在DTO的字段上使用`@NotNull`, `@Size`等声明式注解，并配合Controller层的`@Valid`注解，实现对请求参数的自动化校验。
|
||
|
||
* **对象映射 - `MapStruct`:**
|
||
一个编译期的代码生成器，通过定义`@Mapper`接口，自动生成Entity与DTO之间转换的高性能实现代码，提升了开发效率。
|
||
|
||
* **编程语言与辅助工具:**
|
||
* **`Java 17 (LTS)`:** 使用其`record`、`switch`表达式等新特性编写更简洁的代码。
|
||
* **`Lombok`:** 通过`@Data`, `@Builder`等注解，消除样板代码。
|
||
* **`SLF4J` & `Logback`:** 灵活的日志系统，通过配置文件实现分环境、分级别的日志输出。
|
||
|
||
## 2.3 前端技术栈
|
||
|
||
采用`Vue.js`生态的最新技术，构建响应迅速、代码可维护的现代化单页应用（SPA）。
|
||
|
||
* **核心框架 - `Vue.js 3.x`:**
|
||
利用其两大核心新特性：
|
||
* **`Composition API` (组合式API):** 将相关逻辑组织在同一个`setup`函数内，提高了代码的可读性、可维护性和逻辑复用性。
|
||
* **`Proxy`-based Reactivity:** 基于`Proxy`重写的响应式系统，解决了`Vue 2`中无法监听对象属性新增/删除等痛点。
|
||
|
||
* **构建工具 - `Vite`:**
|
||
新一代前端构建工具，优势在于：
|
||
* 利用浏览器原生ESM支持，实现开发环境下的极速冷启动和闪电般的热模块替换（HMR）。
|
||
* 生产环境使用`Rollup`打包，生成高度优化的静态资源。
|
||
|
||
* **状态管理 - `Pinia`:**
|
||
`Vue`官方推荐的下一代状态管理库，特点是API直观、类型支持完美，且天生模块化。废除了`Vuex`中复杂的`Mutations`等概念，心智负担小。
|
||
|
||
* **UI组件库 - `Element Plus`:**
|
||
`Element UI`的`Vue 3`版本，是一套高质量的企业级UI组件库，提供了丰富的组件，极大地加速了界面的开发进程。
|
||
|
||
* **HTTP客户端 - `Axios`封装:**
|
||
对流行的`Axios`库进行二次封装：
|
||
* **创建实例:** 为API服务设置不同的`baseURL`、`timeout`等。
|
||
* **请求拦截器:** 统一添加认证`token`。
|
||
* **响应拦截器:** 统一处理业务数据和错误状态码。
|
||
|
||
## 2.4 测试技术
|
||
|
||
* **后端单元与集成测试 (`JUnit 5`, `Mockito`, `Spring Boot Test`):**
|
||
使用`spring-boot-starter-test`集成的测试套件保障业务逻辑正确性。
|
||
* **`JUnit 5`:** 测试的基础框架。
|
||
* **`Mockito`:** 在单元测试中用于模拟依赖对象（如Repository），实现测试隔离。
|
||
* **`Spring Boot Test`:** 用于集成测试，加载完整应用上下文，测试跨层级的真实交互场景。
|
||
|
||
* **API接口测试 (`Postman` / `Swagger UI`):**
|
||
* **`Swagger UI`:** 通过集成`SpringDoc`，根据代码注解自动生成交互式API文档，方便调试。
|
||
* **`Postman`:** 用于执行更复杂的API测试场景、编写测试用例和自动化测试。
|
||
|
||
## 2.5 开发工具与环境
|
||
|
||
* **IDE:** 后端使用`IntelliJ IDEA Ultimate`，前端使用`Visual Studio Code`。
|
||
* **项目管理与构建:** 后端使用`Maven`，前端使用`npm`。
|
||
* **版本控制:** `Git` & `GitHub`，遵循`Git Flow`工作流。
|
||
|
||
# 3. 实践结果
|
||
|
||
此部分属报告的主要部分。包括：
|
||
|
||
## 3.1 需求定义
|
||
|
||
"系统分析"也可以看成是需求定义，包括对整个项目的介绍分析及本人工作内容的详细分析，如业务分析、功能分析（可使用例图、活动图来描述）、可行性分析等；
|
||
|
||
## 3.2 系统设计
|
||
|
||
"系统设计"包括总体设计和详细设计，"总体设计"包括系统架构设计、功能模块划分等，"详细设计"要围绕本人工作内容展开，包括功能模块详细设计、类和对象的设计、动态模型设计（时序图、状态图、协作图等）、算法设计、数据库设计等；
|
||
|
||
## 3.3 系统实现
|
||
|
||
"系统实现"也要围绕本人工作内容展开，从编码实现角度论述相应功能模块的实现细节，并展示自己所完成的主要成果及实际应用情况等。可通过"程序流程图"、"关键代码"和"界面"进行直观论述。
|
||
|
||
## 3.4 系统测试
|
||
|
||
"系统测试"包括测试方案设计、测试用例和测试结果、最终的测试结论或评价等。
|
||
|
||
# 4. 实践总结
|
||
|
||
简述你在实践过程中的内容完成情况，重点介绍创新点及不足（也就是可以再完善的部分，只是时间不允许了。不足不代表不好，也说明你思考了，但是来不及完成实现）
|
||
|
||
# 5. 参考资料
|
||
|
||
例：
|
||
[1] 数据结构、算法与应用：C++语言描述 [Data Structures,Algorithms,and Applications in C++][M].机械工业出版社出版时间：2000-01-01.
|
||
[2] 数据结构(C语言版) [M].北京: 中国铁道出版社, 2011-08-01.
|