SCR注解迁移OSGi注解遇Maven报错：注解不适用于该声明

核心错误原因 #

1. @Reference注解的bind/unbind参数用法错误
   新的OSGi Component注解（org.osgi.service.component.annotations.Reference）不支持在字段上使用bind/unbind参数，这两个参数仅能用于方法级别的@Reference注解。旧SCR注解允许在字段上指定bind/unbind，但新注解规范中，字段级@Reference仅用于自动注入单个服务实例，自定义绑定逻辑必须将@Reference标注在bind方法上。

2. 字段类型与注解不匹配
   你将@Reference标注在ConcurrentMap<String, Client>类型的字段上，但OSGi的@Reference注解默认用于注入服务实例，而非自动收集多个服务到自定义映射Map中。要实现按ID维护服务实例的Map，必须通过bind/unbind方法手动处理。

修正后的代码 #

package com.path.http.impl;

import com.path.http.ClientManager;
import com.path.http.ConnectionManager;
import com.path.http.impl.DefaultConnectionManagerImpl;
import org.apache.sling.commons.osgi.PropertiesUtil;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.component.annotations.ReferenceCardinality;
import org.osgi.service.component.annotations.ReferencePolicy;

import jakarta.ws.rs.client.Client;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;

@Component(service = ClientManager.class)
public final class DefaultClientManager implements ClientManager {
    private final ConcurrentMap<String, Client> clients = new ConcurrentHashMap<>();

    // 将@Reference移至bind方法，指定unbind方法
    @Reference(
        cardinality = ReferenceCardinality.MULTIPLE,
        policy = ReferencePolicy.DYNAMIC,
        unbind = "unbindConnectionManager",
        service = ConnectionManager.class
    )
    protected void bindConnectionManager(final ConnectionManager connectionManager,
                                         final Map<String, Object> properties) {
        this.clients.put(
            PropertiesUtil.toString(properties.get(DefaultConnectionManagerImpl.MANAGER_ID), ""),
            connectionManager.getClient()
        );
    }

    protected void unbindConnectionManager(final ConnectionManager connectionManager,
                                           final Map<String, Object> properties) {
        this.clients.remove(
            PropertiesUtil.toString(properties.get(DefaultConnectionManagerImpl.MANAGER_ID), "")
        );
    }

    @Override
    public Optional<Client> getClient(final String id) {
        return Optional.ofNullable(this.clients.get(id));
    }
}

关键细节说明 #

1. bind/unbind方法的属性传递
   新OSGi注解中，bind/unbind方法仍可接收服务属性Map，只要方法签名包含Map<String, Object>参数，框架会自动注入服务的属性集合，你的原有方法签名是正确的。

2. @Reference的正确使用场景

   • 字段级@Reference：用于自动注入单个服务实例，例如@Reference private ConnectionManager connectionManager;
   • 方法级@Reference：用于自定义多服务的绑定/解绑逻辑，处理MULTIPLE基数的服务时必须采用这种方式，手动维护集合或映射关系。

3. 依赖与环境适配
   你使用的org.osgi.service.component.annotations:1.5.1兼容Java 8，且适配AEM 6.5.15版本，无需调整依赖。将javax.ws.rs替换为jakarta.ws.rs的改动符合Jersey 3.x版本的要求，是正确的。

编译错误的彻底解决 #

• 第一个错误（找不到bind方法）：新@Reference注解确实没有bind()属性，bind方法本身就是标注@Reference的方法，无需额外指定。
• 第二个错误（注解不适用该声明）：@Reference不能标注在ConcurrentMap类型字段上，OSGi仅支持将多服务自动注入到Collection或数组中（且是服务实例的集合，而非自定义ID映射的Map），因此必须通过bind/unbind方法手动维护Map。

内容的提问来源于stack exchange，提问作者Jaft