fix: 修复 MockMvcListener 无限等待导致测试卡死问题

[CodeCasterX]

🔗 相关问题 / Related Issue

Issue 链接 / Issue Link: #395

• 我已经创建了相关 Issue 并进行了讨论 / I have created and discussed the related issue
• 这是一个微小的修改(如错别字),不需要 Issue / This is a trivial change (like typo fix) that doesn't need an issue

📋 变更类型 / Type of Change

• 🐛 Bug 修复 / Bug fix (non-breaking change which fixes an issue)
• ✨ 新功能 / New feature (non-breaking change which adds functionality)
• 💥 破坏性变更 / Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 文档更新 / Documentation update
• 🔧 重构 / Refactoring (no functional changes)
• ⚡ 性能优化 / Performance improvement
• 📦 依赖升级 / Dependency upgrade (update dependencies to newer versions)
• 🚀 功能增强 / Feature enhancement (improve existing functionality without breaking changes)
• 🧹 代码清理 / Code cleanup

📝 变更目的 / Purpose of the Change

修复 MockMvcListener 在等待 Mock MVC 服务器启动时无限等待的问题。当服务器因端口占用或其他原因无法启动时,测试会永久卡死而不是快速失败并提供明确的错误信息。

📋 主要变更 / Brief Changelog

• 为 MockMvcListener 添加启动超时机制,默认超时时间为 30 秒
• 支持通过系统属性 fit.test.mockmvc.startup.timeout 自定义超时时间
• 超时时提供详细的错误信息,包括端口、故障排查步骤等
• 添加超时配置的边界检查,最小 1 秒,最大 10 分钟
• 将 isStarted() 方法的可见性改为 protected 以便测试
• 添加完整的单元测试覆盖超时场景、延迟启动、配置验证等

🧪 验证变更 / Verifying this Change

测试步骤 / Test Steps

1. 运行新增的单元测试: mvn test -Dtest=MockMvcListenerTest
2. 验证超时场景: 测试在服务器不可用时能正确超时并抛出异常
3. 验证延迟启动场景: 测试在服务器延迟启动时能正常等待并成功
4. 验证配置边界: 测试非法配置、负数、零值、过大值等边界情况

测试覆盖 / Test Coverage

• 我已经添加了单元测试 / I have added unit tests
• 所有现有测试都通过 / All existing tests pass
• 我已经进行了手动测试 / I have performed manual testing

新增测试覆盖:

• shouldTimeoutWhenServerNotStarted: 验证超时机制
• shouldStartWhenServerAvailable: 验证延迟启动场景
• shouldFallbackToDefaultTimeoutWhenInvalidConfig: 验证非法配置处理
• shouldFallbackToDefaultWhenNegativeTimeout: 验证负数配置处理
• shouldFallbackToDefaultWhenZeroTimeout: 验证零值配置处理
• shouldClampWhenTooLargeTimeout: 验证超大值配置处理

📸 截图 / Screenshots

N/A

✅ 贡献者检查清单 / Contributor Checklist

基本要求 / Basic Requirements:

• 确保有 GitHub Issue 对应这个变更(微小变更如错别字除外)/ Make sure there is a Github issue filed for the change (trivial changes like typos excluded)
• 你的 Pull Request 只解决一个 Issue,没有包含其他不相关的变更 / Your PR addresses just this issue, without pulling in other changes - one PR resolves one issue
• PR 中的每个 commit 都有有意义的主题行和描述 / Each commit in the PR has a meaningful subject line and body

代码质量 / Code Quality:

• 我的代码遵循项目的代码规范 / My code follows the project's coding standards
• 我已经进行了自我代码审查 / I have performed a self-review of my code
• 我已经为复杂的代码添加了必要的注释 / I have commented my code, particularly in hard-to-understand areas

测试要求 / Testing Requirements:

• 我已经编写了必要的单元测试来验证逻辑正确性 / I have written necessary unit-tests to verify the logic correction
• 当存在跨模块依赖时,我尽量使用了 mock / I have used mocks when cross-module dependencies exist
• 基础检查通过:mvn -B clean package -Dmaven.test.skip=true / Basic checks pass
• 单元测试通过:mvn clean install / Unit tests pass

文档和兼容性 / Documentation and Compatibility:

• 我已经更新了相应的文档 / I have made corresponding changes to the documentation
• 如果有破坏性变更,我已经在 PR 描述中详细说明 / If there are breaking changes, I have documented them in detail
• 我已经考虑了向后兼容性 / I have considered backward compatibility

📋 附加信息 / Additional Notes

设计考虑

1. 超时时间选择: 默认 30 秒对于大多数环境足够,同时不会让开发者等待过久
2. 可配置性: 通过系统属性支持自定义超时,适应不同环境需求
3. 边界保护: 限制最小/最大超时时间,防止配置错误导致问题
4. 错误信息: 提供详细的故障排查步骤,帮助开发者快速定位问题
5. 向后兼容: 不改变现有 API,仅增加超时保护机制

影响范围

• 仅影响使用 @EnableMockMvc 注解的测试类
• 对正常启动的场景无影响
• 对启动失败的场景,从无限等待改为快速失败

---

审查者注意事项 / Reviewer Notes:

• 请重点关注超时错误信息是否足够清晰
• 请验证测试覆盖是否充分
• 请检查是否有其他需要添加超时保护的地方

🤖 Generated with Claude Code