package com.zsElectric.boot.common.annotation;

import java.lang.annotation.*;
import java.util.concurrent.TimeUnit;

/**
 * API接口限流注解
 * <p>
 * 用于对外部第三方接口进行限流控制，支持基于IP和全局的限流策略
 *
 * @author system
 * @since 2025-12-19
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface ApiRateLimit {

    /**
     * 限流key前缀（用于区分不同接口）
     * <p>
     * 默认为空，使用方法签名作为key
     */
    String prefix() default "";

    /**
     * 限流类型
     */
    LimitType limitType() default LimitType.IP;

    /**
     * 时间窗口内允许的最大请求次数
     * <p>
     * 默认100次
     */
    int count() default 100;

    /**
     * 时间窗口大小
     * <p>
     * 默认60秒
     */
    long time() default 60;

    /**
     * 时间单位
     * <p>
     * 默认秒
     */
    TimeUnit timeUnit() default TimeUnit.SECONDS;

    /**
     * 限流提示信息
     */
    String message() default "请求过于频繁，请稍后再试";

    /**
     * 限流类型枚举
     */
    enum LimitType {
        /**
         * 基于IP地址限流
         */
        IP,

        /**
         * 全局限流（所有请求共享配额）
         */
        GLOBAL,

        /**
         * 基于用户限流（需要用户登录）
         */
        USER
    }
}
