Java Web应用WebSocket握手阶段返回404错误如何排查？

404错误常见成因及对应解决方法 #

• 部署上下文路径不匹配 #

你代码中wsUri指定的上下文路径为/ColloborativeWhiteBoard，但实际GlassFish部署时的上下文路径大概率不一致：

• 排查方式：启动GlassFish后访问管理控制台，查看当前应用的部署上下文路径；或检查target目录下生成的war包名称，默认会带上版本号为ColloborativeWhiteBoard-1.0-SNAPSHOT.war，对应上下文路径就是/ColloborativeWhiteBoard-1.0-SNAPSHOT
• 解决方法：
  1. 直接修改wsUri中的上下文路径和实际部署路径保持一致
  2. 或在pom.xml的maven-war-plugin配置中添加<finalName>ColloborativeWhiteBoard</finalName>，打包后war包不带版本号，上下文路径和你代码中的配置一致
     示例配置：

  <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-war-plugin</artifactId>
      <version>3.3.1</version>
      <configuration>
          <finalName>ColloborativeWhiteBoard</finalName>
      </configuration>
  </plugin>
  

• WebSocket端点未被容器扫描注册 #

GlassFish需要扫描到@ServerEndpoint注解才会注册对应的WebSocket端点，未扫描到就会返回404：

• 排查方式：检查项目是否存在web.xml，如果存在确认web-app标签的版本号≥3.1，且未配置metadata-complete="true"（该配置会关闭注解扫描）
• 解决方法：
  1. 若无web.xml文件，可手动添加WebSocket扫描配置类，示例代码如下：

  import javax.websocket.server.ServerApplicationConfig;
  import javax.websocket.server.ServerEndpointConfig;
  import java.util.Set;
  
  public class WebSocketConfig implements ServerApplicationConfig {
      @Override
      public Set<ServerEndpointConfig> getEndpointConfigs(Set<Class<? extends javax.websocket.Endpoint>> set) {
          return null;
      }
  
      @Override
      public Set<Class<?>> getAnnotatedEndpointClasses(Set<Class<?>> scanned) {
          // 这里返回你的端点类，也可以直接返回scanned让容器扫描所有带注解的类
          return Set.of(boardServer.class);
      }
  }
  

  2. 若存在web.xml，将web-app版本升级到3.1及以上，删除metadata-complete="true"配置

• 其他常见配置错误 #

  1. 确认GlassFish的HTTP监听端口确实为8080，若有修改同步调整wsUri中的端口号
  2. 若你开启了HTTPS访问，需要将ws协议改为wss协议
  3. 确认端点路径大小写完全匹配，Java服务端路径、JS中的路径大小写必须完全一致

内容的提问来源于stack exchange，提问作者A.Eze