前端转计算之SuperMap计算后端-手把手入门教程3
三、JAVA Web 项目创建、配置、编码
1、IDEA 中 创建项目
打开 IDEA，点击 File->New->Project，选择 Spring Boot。
注意设置 Server URL 为 阿里云地址：https://start.aliyun.com/
如果遇到地址报错，如下所示：
注意如上图所示：Type 选择 Maven，Java 要选择 8，JDK 要选择 1.8，Packaging 选择 War。其中 Name、Group、Artifact 可以选择性设置。
点击 Next 后，在新的界面中：
Spring Boot 这里选择 2.6.13，Dependencies 下勾选 Web 下的 Spring Web 即可，然后点击创建即可完成。
这样 JAVA Web 项目就创建完成了。
2、项目基础配置
a. 设置自动导入、Reload
参考如下所示的2个章节，设置即可，这样编写代码时，会自动引入相关依赖。（如果编写代码时，没有自动引入，可重启 idea 软件项目即可。）
⑤设置Maven的Reload操作（注意：每次新建项目都建议设置）
b. 设置 Maven home path、User settings file、Local repository
在 Maven 配置章节中如下：
[b. Maven 配置](#b. Maven 配置)
设置了 Maven 的环境变量，修改了 settings.xml，定义了 localRepository 等位置和内容。
则需要在新建的项目中，通过 idea 的 File->Settings->Build,Execution,Deloyment->Build Tools->Maven 界面，设置 Maven 对应的内容，具体如下图所示：
这里设置的内容均与 Maven 安装时配置的内容一一对应。
Maven home path：D:\03Program\maven\apache-maven-3.6.3
User settings file：D:\03Program\maven\apache-maven-3.6.3\conf\settings.xml
Local repository：D:\maven\jars
3、SuperMap iObjects JAVA 开发包在项目中引入、配置
在项目根目录下新建 lib 文件夹。然后找到 SuperMap iObjects JAVA 的开发包 Bin 下的 所有 .jar 文件，拷贝到 lib 文件夹下。如下图所示：
然后在 lib 文件夹右键，选择 Add as Library，在弹出的 Create Library 界面中，Name 与 lib 文件夹保持同名，然后点击 OK 即可。
然后点击 File->Project Structure，弹出 Project Structure 面板，选中左侧的 Libraries 可以看到，出现了对应的 lib。
然后在 lib 上右键，选择 Add to Modules。
然后在弹出的 Choose Modules 面板中，点击 OK 即可。
这样就可以在代码中使用、引入 SuperMap 相关的依赖了。
4、项目文件、文件夹新建与调整
a. application.yml 设置
新建的项目在 src/main/resources 下会有个 application.properties 文件，在其上方右键，选择 Rename，将其后缀改为 .yml。
然后在 application.yml 中配置开发环境的服务端口，如下所示：
server:
port: 9898
这样在开发环境启动计算服务时，访问的端口即为 9898。
b. web 文件夹下设置 web.xml
有时，有可能 根目录下的 web 文件夹下 没有 web.xml ，此时则需要新建。
此时可以在根目录下的 web 文件夹右键，创建一个名为 WEB-INF 的 Directory。然后再在新建的 WEB-INF 文件夹下右键，新建一个名为 web 的 XML Configuration File。
创建完成后如下所示：
web.xml 中的内容为创建时默认内容即可。
c. src/main/java/com. 目录调整与新建
新建的项目在 src/main/java/com. 下会有一些默认的文件、文件夹。可以删除这些文件、文件夹，只保留 ServletInitializer.java、…Application.java 两个文件。
然后在 ServletInitializer.java 同级目录下，分别新建 config、controller、exception、model、response 文件夹。
这些文件夹的作用为：
config：配置层， 文件夹下用于存放 表示通过 java 代码设置的一些配置
controller：控制层/接口层
exception：全局异常捕获
model：数据层/数据模型
response：统一封装的数据响应
接下来将开始在对应文件夹中编写代码。
d. config 中添加默认配置
① CorsConfig：跨域设置等
后端计算服务接口的 GET/POST/DELETE/PUT 等 Restful 接口的实现， 一般都需要设置一些默认的信息：如是否需要 token、响应时间、是否支持跨域等。
新建 CorsConfig.java 文件，编写代码如下：
CorsConfig.java 完整代码：
package com.gis.tianspace.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* SpringBoot可以基于Cors解决跨域问题，
* Cors是一种机制，设置那些请求可以访问服务器的数据。
*/
@Configuration
public class CorsConfig {
@Bean
public WebMvcConfigurer corsConfigurer() {
return new WebMvcConfigurer() {
// 重写父类提供的跨域请求处理的接口
@Override
public void addCorsMappings(CorsRegistry registry) {
// 添加映射路径
registry.addMapping("/**")
.allowedOriginPatterns("*") // 放行哪些域名，可以多个
.allowCredentials(true) // 是否发送Cookie信息
.allowedMethods("GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS", "PATCH") // 放行哪些请求方式
.allowedHeaders("*") // 放行哪些原始域(头部信息)
.exposedHeaders("Content-Type", "Header2") // 暴露哪些头部信息（因为跨域访问默认不能获取全部头部信息）
.maxAge(3600); // 预请求的结果有效期，默认1800分钟,3600是一小时
}
};
}
}
上面代码中的 @Configuration 就是一种注解。这是 Spring Boot 框架的重要机制：注解。
具体可参考下面文章了解：
springboot常用注解大全(超详细, 30个) - 小liii - 博客园
简单来说：
Spring Boot注解主要用于简化配置、自动装配组件和实现声明式服务。通过注解的方式，Spring Boot 框架就可以直接初始化、运行这些代码。而无需在启动类中再导入相关 JAVA 文件。即框架本身通过识别注解的方式可以批量导入、初始化、运行这些 JAVA 文件及其代码。
如上设置后，就可以避免后续可能遇到的前端请求后端计算接口跨域问题了。
② SpringDocConfig：Swagger 默认配置
写后端计算服务接口，Swagger 是必须。这里通过 SpringDocConfig.java 来设置 Swagger 页面的一些必要参数。
SpringDocConfig.java 完整代码如下：
package com.gis.tianspace.config;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.HashMap;
/**
* ClassName: SpringDocConfig
* Package: com.mcode.swaggertest.config
* Description:
*
* @Author: tian
* @Create: 2025/7/8 - 15:00 PM
* @Version: v1.0
*/
@Configuration
public class SpringDocConfig {
@Bean
public OpenAPI openAPI(){
// 联系人信息(contact)，构建API的联系人信息，用于描述API开发者的联系信息，包括名称、URL、邮箱等
Contact contact = new Contact()
.name("tian") // 作者名称
.email("tian@gmail.com") // 作者邮箱
.url("tian") // 介绍作者的URL地址
.extensions(new HashMap<String,Object>());// 使用Map配置信息（如key为"name","email","url"）
License license = new License()
.name("Apache 2.0") // 授权名称
.url("https://www.apache.org/licenses/LICENSE-2.0.html") // 授权信息
.identifier("Apache-2.0") // 标识授权许可
.extensions(new HashMap<String, Object>());// 使用Map配置信息（如key为"name","url","identifier"）
//创建Api帮助文档的描述信息、联系人信息(contact)、授权许可信息(license)
Info info = new Info()
.title("SuperMap Api 计算接口文档") // Api接口文档标题（必填）
.description("项目描述") // Api接口文档描述
.version("1.0.0") // Api接口版本
.termsOfService("tian") // Api接口的服务条款地址
.license(license) // 授权名称
.contact(contact); // 设置联系人信息
// List<Server> servers = new ArrayList<>(); //多服务
// // 表示服务器地址或者URL模板列表，多个服务地址随时切换（只不过是有多台IP有当前的服务API）
// servers.add(new Server().url("http://localhost:8080").description("服务1"));
// servers.add(new Server().url("http://localhost:8081").description("服务2"));
//
// // // 设置 spring security apikey accessToken 认证的请求头 X-Token: xxx.xxx.xxx
// SecurityScheme securityScheme = new SecurityScheme()
// .name("x-token")
// .type(SecurityScheme.Type.APIKEY)
// .description("APIKEY认证描述")
// .in(SecurityScheme.In.HEADER);
//
// // 设置 spring security jwt accessToken 认证的请求头 Authorization: Bearer xxx.xxx.xxx
// SecurityScheme securityScheme1 = new SecurityScheme()
// .name("JWT认证")
// .scheme("bearer") //如果是Http类型，Scheme是必填
// .type(SecurityScheme.Type.HTTP)
// .description("认证描述")
// .in(SecurityScheme.In.HEADER)
// .bearerFormat("JWT");
//
// List<SecurityRequirement> securityRequirements = new ArrayList<>();
//
// SecurityRequirement securityRequirement = new SecurityRequirement();
// securityRequirement.addList("authScheme");
//
// securityRequirements.add(securityRequirement);
// 返回信息
return new OpenAPI()
//.openapi("3.0.1") // Open API 3.0.1(默认)
.info(info)
// .servers(servers)
// .components(new Components().addSecuritySchemes("authScheme",securityScheme1)) //添加鉴权组件
// .security(securityRequirements) //全部添加鉴权小锁
.externalDocs(new ExternalDocumentation()
.description("对外说明") //对外说明
.url("tian")); // 配置Swagger3.0描述信息
}
}
注意上面引入了 io.swagger.v3 等依赖。需要在 pom.xml 中添加、安装相关依赖。pom.xml 类似于前端的 package.json。
在 pom.xml 的 dependencies 下添加 springdoc 依赖：
<!-- 这个坐标它提供了一组注解和工具来集成Swagger UI和OpenAPI规范等-->
<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.7.0</version>
</dependency>
设置后如下图所示：
如上设置后，后续就可以在 swagger 页面上 看到相关的 swagger 配置了。
e. response 中 封装统一的接口返回格式
① 新建 ResultCodeEnum.java，并设置、封装返回状态等内容
这里主要封装两种请