快速开始指南

本指南将帮助您在5分钟内快速集成Medical License组件到您的Spring Boot医疗软件系统中。

📋 前置条件

Java 8 或更高版本
Spring Boot 2.0 或更高版本
Maven 或 Gradle 构建工具

🚀 快速集成

步骤1: 添加依赖

在您的 pom.xml 中添加依赖：

<dependency>
    <groupId>com.bskj.license</groupId>
    <artifactId>byjc-spring-boot-starter-license</artifactId>
    <version>1.0.0</version>
</dependency>

步骤2: 生成密钥对

# 下载并运行密钥生成工具
java -cp byjc-spring-boot-starter-license-1.0.0.jar com.bskj.framework.license.generator.KeyGenerator private.key public.key

这将生成两个文件：

private.key - 私钥（用于签名license，请安全保存）
public.key - 公钥（用于验证license，可随应用分发）

步骤3: 生成License文件

# 生成license文件
java -cp byjc-spring-boot-starter-license-1.0.0.jar com.bskj.framework.license.generator.LicenseGenerator private.key license.json "您的医院名称"

步骤4: 配置应用

在 application.yml 中添加配置：

bskj:
  license:
    enabled: true
    file-path: "license.json"
    public-key-path: "public.key"
    default-strategy: "notification_only"  # 推荐从宽松策略开始

步骤5: 使用注解控制权限

@RestController
public class PatientController {
    
    @LicenseRequired(modules = {"patient_management"})
    @GetMapping("/patients")
    public List<Patient> getPatients() {
        return patientService.getAllPatients();
    }
}

步骤6: 启动应用

java -jar your-bskj-app.jar

🎉 恭喜！ 您的应用现在已经集成了License授权功能！

🔧 常用配置

基础配置

bskj:
  license:
    enabled: true                          # 启用license检查
    file-path: "license.json"              # license文件路径
    public-key-path: "public.key"          # 公钥文件路径
    default-strategy: "notification_only"  # 授权策略
    check-interval-seconds: 3600           # 检查间隔（1小时）
    default-warning-days: 30               # 预警天数

通知配置

bskj:
  license:
    notification:
      log-enabled: true                    # 启用日志通知
      email-enabled: false                # 禁用邮件通知（可选）
      jmx-enabled: false                   # 禁用JMX通知（可选）

📝 常用注解

@LicenseRequired 注解参数

@LicenseRequired(
    modules = {"billing", "reporting"},     // 需要的模块权限
    checkUserLimit = true,                   // 检查用户数限制
    allowExpired = false,                    // 是否允许过期时执行
    strict = false,                          // 严格模式
    message = "需要计费和报表模块授权"        // 自定义错误消息
)

常用场景

// 基础权限检查
@LicenseRequired(modules = {"patient_management"})

// 检查用户数限制
@LicenseRequired(checkUserLimit = true)

// 严格模式（任何license问题都阻止执行）
@LicenseRequired(strict = true)

// 允许过期时执行（紧急功能）
@LicenseRequired(modules = {"emergency"}, allowExpired = true)

🎯 授权策略说明

1. NOTIFICATION_ONLY（推荐开始使用）

✅ 系统正常运行
✅ 仅通过日志/通知提醒
✅ 不影响业务功能
🎯 适合：对业务连续性要求极高的场景

2. PREVENT_RESTART

✅ 当前服务继续运行
❌ 阻止应用重新启动
🎯 适合：平衡业务连续性和授权控制

3. GRACEFUL_SHUTDOWN

⏰ 提供宽限期
❌ 宽限期后停止服务
❌ 阻止重新启动
🎯 适合：给客户充足续费时间

🛠️ 编程式使用

@Service
public class BusinessService {
    
    @Autowired
    private LicenseService licenseService;
    
    public void performOperation() {
        // 检查license状态
        if (!licenseService.isLicenseValid()) {
            throw new BusinessException("License无效");
        }
        
        // 检查模块权限
        if (!licenseService.isModulePermitted("advanced_features")) {
            throw new BusinessException("高级功能未授权");
        }
        
        // 检查用户数限制
        if (!licenseService.isUserCountWithinLimit(getCurrentUserCount())) {
            throw new BusinessException("用户数超过限制");
        }
        
        // 执行业务逻辑
        doBusinessLogic();
    }
}

📊 监控License状态

REST API方式

@RestController
public class LicenseController {
    
    @Autowired
    private LicenseService licenseService;
    
    @GetMapping("/api/license/status")
    public Map<String, Object> getLicenseStatus() {
        return Map.of(
            "valid", licenseService.isLicenseValid(),
            "status", licenseService.getLicenseStatus(),
            "remainingDays", licenseService.getRemainingDays(),
            "warning", licenseService.getLicenseWarningMessage()
        );
    }
}

事件监听方式

@Component
public class LicenseEventListener {
    
    @EventListener
    public void handleStatusChange(LicenseStatusChangeEvent event) {
        logger.info("License状态变化: {} -> {}", 
            event.getPreviousStatus(), event.getCurrentStatus());
    }
}

🔍 故障排除

常见问题

Q: 应用启动时提示"License文件不存在"

# 检查配置文件中的路径是否正确
bskj:
  license:
    file-path: "license.json"  # 确保文件存在

Q: 提示"签名验证失败"

# 确保使用正确的公钥文件
# 检查license文件是否被篡改

Q: 注解不生效

// 确保启用了AOP
@EnableAspectJAutoProxy
@SpringBootApplication
public class Application {
    // ...
}

调试模式

logging:
  level:
    com.bskj.license: DEBUG  # 启用详细日志

📈 生产环境建议

安全建议

🔐 私钥文件安全保存，不要包含在应用中
🔐 使用HTTPS传输license文件
🔐 定期更换密钥对
🔐 监控license文件访问日志

部署建议

📁 将license和公钥文件放在应用外部目录
📁 使用绝对路径配置文件位置
📁 设置适当的文件权限

监控建议

📊 启用邮件通知给管理员
📊 监控license状态变化
📊 设置合适的检查间隔
📊 建立license续费提醒流程

🎓 进阶使用

查看完整文档：

README.md - 完整功能说明
example/ - 完整示例代码
application-license-example.yml - 详细配置示例

💬 技术支持

如有问题，请查看：

QUICK_START.md 7.0 KB 永久連結 文件歷史 原始文件