[Android] 안드로이드 SDK에 포함된 어노테이션

출처

ChatGPT

---

1. @RequiresPermission

• 해당 메서드나 클래스가 호출될 떄 필요한 권한을 컴파일 타임에 명시적으로 알 수 있다. 이를 통해 실수로 권한을 요청하지 않은 상태에서 메소드를 호출하는 것을 방지한다.
• 코드를 읽는 읽는 다른 개발자에게 이 메서드나 클래스가 특정 권한을 요구한다는 것을 명확히 전달할 수 있어 유지보수성을 높인다.
• 안드로이드 Lint 도구는 이 어노테이션을 사용해 권한이 적절하게 요청되고 있는 검사한다. 
• 도입 시기 : API 레벨 16 (Jelly Bean)부터.

import android.Manifest
import android.content.Context
import android.net.wifi.WifiManager
import androidx.annotation.RequiresPermission

class WifiController(private val context: Context) {

    private val wifiManager: WifiManager = context.getSystemService(Context.WIFI_SERVICE) as WifiManager

    @RequiresPermission(Manifest.permission.ACCESS_WIFI_STATE)
    fun isWifiEnabled(): Boolean {
        return wifiManager.isWifiEnabled
    }

    @RequiresPermission(Manifest.permission.CHANGE_WIFI_STATE)
    fun setWifiEnabled(enabled: Boolean) {
        wifiManager.isWifiEnabled = enabled
    }
}

 

이 코드에서는 ACCESS_WIFI_STATE와 CHANGE_WIFI_STATE 권한이 각각 필요함을 명시하고 있다.

 

2. @Nullable 및 @NonNull

• @Nullable: 해당 변수, 메서드 반환 값, 또는 메서드 매개변수가 null일 수 있음을 나타낸다.
• @NonNull: 해당 요소가 null이 될 수 없음을 나타낸다.
• 두 어노테이션은 자바에서 유용하다. 코틀린은 Null-Safety를 언어 수준에서 지원한다.
• 도입 시기: 초기 안드로이드 버전부터 존재했지만, API 레벨 19 (KitKat) 이후로 안드로이드 SDK에서 공식 지원되었다.

import androidx.annotation.NonNull;
import androidx.annotation.Nullable;

public class UserManager {

    // 이 메서드는 절대 null을 반환하지 않음을 명시
    @NonNull
    public String getUserName() {
        return "John Doe";
    }

    // 이 메서드는 null을 반환할 수 있음을 명시
    @Nullable
    public String getUserNickname() {
        // 사용자에게 별명이 없을 수도 있음
        return null;
    }

    // 이 메서드는 null이 될 수 없는 파라미터를 받아야 함을 명시
    public void printUserName(@NonNull String userName) {
        System.out.println("User name: " + userName);
    }

    // 이 메서드는 null이 될 수 있는 파라미터를 받아 처리
    public void printUserNickname(@Nullable String userNickname) {
        if (userNickname != null) {
            System.out.println("User nickname: " + userNickname);
        } else {
            System.out.println("User has no nickname");
        }
    }

    public static void main(String[] args) {
        UserManager userManager = new UserManager();

        // NonNull 반환값은 null 체크가 필요 없음
        String userName = userManager.getUserName();
        userManager.printUserName(userName);

        // Nullable 반환값은 null 체크가 필요함
        String userNickname = userManager.getUserNickname();
        userManager.printUserNickname(userNickname);

        // NonNull 파라미터에 null을 전달하려고 하면 컴파일 오류 발생
        // userManager.printUserName(null); // 컴파일 오류

        // Nullable 파라미터에는 null을 전달할 수 있음
        userManager.printUserNickname(null);
    }
}

 

 

1. @NonNull:
   • getUserName() 메서드는 절대 null을 반환하지 않도록 보장한다.
   • printUserName() 메서드는 null이 아닌 값을 받아야 한다는 것을 명시한다.
2. @Nullable:
   • getUserNickname() 메서드는 null을 반환할 수 있음을 나타내고, 사용자는 반환 값을 사용할 때 반드시 null 체크를 해야 한다.
   • printUserNickname() 메서드는 null일 수 있는 파라미터를 받아 처리한다.
3. 메인 메서드:
   • getUserName()의 반환값은 NonNull로 지정되었기 때문에, 별도의 null 체크 없이 바로 사용할 수 있다.
   • 반면 getUserNickname()은 Nullable로 지정되었기 때문에, 반환된 값이 null일 가능성을 고려해 null 체크를 해야 한다.

 

 

3. @UiThread, @MainThread, @WorkerThread

• @UiThread: 메서드가 UI 스레드에서 호출되어야 함을 나타낸다.
• @MainThread: 메서드가 메인 스레드에서 호출되어야 함을 나타낸다 (주로 UI 스레드를 의미한다).
• @WorkerThread: 메서드가 백그라운드 스레드에서 호출되어야 함을 나타낸다.
• 도입 시기: API 레벨 21 (Lollipop)부터.

import android.os.AsyncTask
import androidx.annotation.UiThread
import androidx.annotation.WorkerThread

class DataFetcher {

    @WorkerThread
    fun fetchData(): String {
        // 이 메서드는 백그라운드 스레드에서 실행되어야 함
        Thread.sleep(1000) // 데이터 가져오기 시뮬레이션
        return "Data"
    }

    @UiThread
    fun displayData(data: String) {
        // 이 메서드는 UI 스레드에서 실행되어야 함
        println("Displaying data: $data")
    }

    fun startFetching() {
        AsyncTask.execute {
            val data = fetchData() // 백그라운드에서 데이터 가져오기
            displayData(data) // UI 스레드에서 데이터 표시
        }
    }
}

 

여기서는 @WorkerThread와 @UiThread를 사용해 각각의 메서드가 어디서 실행되어야 하는지 명시한다.

 

4. @CheckResult

• @CheckResult: 메서드 호출 결과를 반드시 확인해야 함을 나타낸다. 결과를 확인하지 않으면 중요한 동작을 놓칠 수 있다는 경고를 Lint를 통해 받을 수 있다.
• 도입 시기: API 레벨 17 (Jelly Bean MR1)부터.

import androidx.annotation.CheckResult

@CheckResult
fun calculateSum(a: Int, b: Int): Int {
    return a + b
}

fun main() {
    val result = calculateSum(3, 4) // 올바른 사용
    println("Sum: $result")

    // calculateSum(3, 4) // 이 줄에서 Lint가 결과를 사용하지 않는다고 경고할 것
}

 

@CheckResult는 반환값이 사용되지 않을 때 경고를 표시해 실수를 방지할 수 있.

 

5. @VisibleForTesting

• @VisibleForTesting: 특정 메서드, 필드 또는 클래스가 테스트 목적으로만 접근 가능함을 나타낸다. 예를 들어, 일반적으로는 private이지만 테스트에서는 접근 가능하도록 할 때 사용한다.
• 도입 시기: API 레벨 21 (Lollipop)부터.

import androidx.annotation.VisibleForTesting

class Calculator {

    fun add(a: Int, b: Int): Int {
        return a + b
    }

    @VisibleForTesting
    internal fun subtract(a: Int, b: Int): Int {
        return a - b
    }
}

 

subtract 메서드는 주로 테스트 목적으로만 공개되며, 일반적으로는 internal로 유지된다.

 

• 왜 예제 코드에서 @VisibleForTesting 어노테이션이 붙은 subtract() 메서드에 internal 접근 제한자를 사용한 것인가

왜 예제 코드에서 @VisibleForTesting 어노테이션이 붙은 subtract() 메서드에 internal 접근 제한자를 사용한 것인가

 

@VisibleForTesting와 internal의 역할

• @VisibleForTesting: 이 어노테이션은 메서드나 필드가 원래는 제한된 접근 수준(예: private, internal)을 가지지만, 테스트 목적으로 접근할 수 있게 하려는 의도를 명시할 때 사용된다. 즉, 이 어노테이션은 "이 코드는 원래는 외부에 노출되지 말아야 하지만, 테스트를 위해 접근 가능해야 한다"는 의도를 나타내는 것이다.
• internal 접근 제한자: 코틀린에서 internal은 해당 멤버가 같은 모듈 내에서만 접근 가능하게 하는 접근 제한자다. 따라서 internal로 선언된 메서드나 필드는 같은 모듈 내의 다른 클래스나 함수에서 접근할 수 있지만, 모듈 외부에서는 접근할 수 없다.

 

예제 코드에서 subtract()에 internal을 사용한 이유

class Calculator {

    fun add(a: Int, b: Int): Int {
        return a + b
    }

    @VisibleForTesting
    internal fun subtract(a: Int, b: Int): Int {
        return a - b
    }
}

 

이 코드에서 subtract() 메서드가 internal로 선언된 이유는 테스트 목적으로는 접근할 수 있지만, 실제 애플리케이션 코드에서는 외부에 노출되지 않도록 하기 위해서.

 

1. 모듈의 캡슐화 유지

• subtract() 메서드는 본래 private으로 두어야 할 메서드일 수 있다. 그러나 테스트 코드에서는 이 메서드를 호출해 테스트하고 싶을 때가 있다. 이때 @VisibleForTesting 애노테이션을 사용해 이 메서드가 테스트를 위해서만 존재한다고 명시하는 것이다.
• 동시에 internal을 사용하면 같은 모듈 내에서만 접근할 수 있도록 제한해, 외부 라이브러리나 다른 모듈에서는 이 메서드에 접근할 수 없다. 이는 모듈의 캡슐화를 유지하면서도, 테스트의 편의성을 확보할 수 있는 방법이다.

2. 모듈 외부에서의 접근 방지

• 만약 subtract() 메서드를 public으로 선언하면, 이 메서드는 애플리케이션의 모든 부분에서 접근할 수 있게 된다. 그러나 이 메서드가 테스트 목적으로만 사용되기를 원할 경우, public으로 만드는 것은 부적절할 수 있다.
• internal로 제한하면, 이 메서드는 같은 모듈 내에서만 사용 가능하고 외부에서는 접근할 수 없게 되므로, 불필요하게 외부에 노출되지 않아도 된다.

 

internal로 유지할 필요가 없을 때

만약 subtract() 메서드가 테스트뿐만 아니라 다른 클래스나 모듈에서도 사용되길 원한다면 public으로 선언할 수 있다. 이렇게 하면 모든 코드에서 접근 가능해지지만, 이 경우에는 @VisibleForTesting을 사용하는 목적이 희석될 수 있어다

그러나 예제에서는 이 메서드가 테스트 목적으로만 노출되기를 원했기 때문에, internal로 제한을 두어 다른 모듈에서는 접근할 수 없도록 한 것이.

 

결론

• @VisibleForTesting은 테스트를 위해 원래는 제한된 접근 수준을 가진 메서드를 노출할 때 사용된다.
• internal은 모듈의 경계를 넘지 않는 선에서만 메서드가 사용되도록 제한해, 모듈의 캡슐화를 유지하면서도 테스트를 가능하게 해준다.
• 이 접근법은 코드의 안전성을 높이고, 의도치 않은 사용을 방지하는 데 도움이 된다.

 

6. @CallSuper

• @CallSuper: 오버라이드된 메서드에서 반드시 슈퍼 클래스의 해당 메서드를 호출해야 함을 나타낸다. 그렇지 않으면 예상치 못한 동작이 발생할 수 있다.
• 도입 시기: API 레벨 21 (Lollipop)부터.

import androidx.annotation.CallSuper

open class Animal {
    @CallSuper
    open fun makeSound() {
        println("Animal sound")
    }
}

class Dog : Animal() {
    override fun makeSound() {
        super.makeSound() // 반드시 호출해야 함
        println("Bark")
    }
}

 

여기서는 @CallSuper를 사용해 서브클래스가 부모 클래스의 메서드를 반드시 호출하도록 명시했다.

 

7. @Size

• @Size: 컬렉션, 배열, 문자열 등의 크기 또는 길이에 대한 제한을 나타낸다. 예를 들어, 특정 배열의 크기가 10이어야 함을 명시할 수 있다.
• 도입 시기: API 레벨 21 (Lollipop)부터.

import androidx.annotation.Size

fun setScores(@Size(min = 1, max = 5) scores: IntArray) {
    println("Scores: ${scores.joinToString()}")
}

fun main() {
    setScores(intArrayOf(10, 20, 30)) // 올바른 사용
    // setScores(intArrayOf()) // Lint가 경고를 표시함 (크기가 1 이상이어야 함)
}

 

@Size를 사용해 배열의 크기에 대한 제약을 명시할 수 있다.

 

8. @IntDef 및 @StringDef

• @IntDef: 특정 메서드 또는 변수에 허용되는 정수 값을 정의하는 데 사용한다. 이것은 열거형의 대안으로 사용할 수 있어, 성능 최적화를 위해 사용되기도 한다.

• 관련 글 -> [Java][Android] 자바의 열거형(enum)의 대체로 나왔다는 @IntDef, 그렇다면 열거형은 어떤 문제가 있는 걸까

• @StringDef: 특정 메서드 또는 변수에 허용되는 문자열 값을 정의하는 데 사용한다. 문자열 상수의 유효성을 검사하기 위해 도입됐다. 잘못된 문자열 값의 사용을 방지한다.
• 도입 시기: API 레벨 19 (KitKat)부터.

import androidx.annotation.IntDef

const val MODE_A = 0
const val MODE_B = 1

@IntDef(MODE_A, MODE_B)
@Retention(AnnotationRetention.SOURCE)
annotation class Mode

fun setMode(@Mode mode: Int) {
    println("Mode set to $mode")
}

fun main() {
    setMode(MODE_A) // 올바른 사용
    // setMode(2) // 컴파일러가 잘못된 값이라고 경고함
}

 

@IntDef는 허용되는 정수 값을 제한해 타입 안전성을 높여준다.

 

import androidx.annotation.StringDef;

public class NetworkManager {

    public static final String WIFI = "WIFI";
    public static final String MOBILE = "MOBILE";
    public static final String ETHERNET = "ETHERNET";

    @StringDef({WIFI, MOBILE, ETHERNET})
    @Retention(RetentionPolicy.SOURCE)
    public @interface NetworkType {}

    private String currentNetworkType = WIFI;

    public void setNetworkType(@NetworkType String networkType) {
        this.currentNetworkType = networkType;
    }

    @NetworkType
    public String getNetworkType() {
        return currentNetworkType;
    }
}

 

9. @Keep

• @Keep: 프로가드(ProGuard)나 R8 같은 코드 압축기에서 클래스, 메서드, 필드가 제거되거나 난독화되지 않도록 보호할 때 사용한다.
• 도입 시기: API 레벨 21 (Lollipop)부터.

import androidx.annotation.Keep

@Keep
class ImportantClass {
    fun doSomething() {
        println("Doing something important")
    }
}

 

@Keep을 사용하면 ProGuard나 R8이 이 클래스와 그 메서드를 제거하거나 난독화하지 않도록 보호할 수 있다.

 

10. @RequiresApi

• @RequiresApi: 메서드나 클래스가 특정 API 레벨 이상에서만 사용 가능함을 나타낸다.
• 도입 시기: API 레벨 19 (KitKat)부터.

import android.os.Build
import androidx.annotation.RequiresApi

@RequiresApi(Build.VERSION_CODES.O)
fun useNewApiFeature() {
    // Android O (API 26) 이상에서만 실행되는 코드
    println("Using Android O feature")
}

 

@RequiresApi는 특정 API 레벨 이상에서만 사용할 수 있는 메서드나 클래스를 명시할 때 사용된다.

 

11. @TargetApi

• 해당 메서드, 클래스, 또는 필드가 특정 API 레벨에서만 사용될 수 있음을 문서화한다. 이를 통해 코드 리뷰어와 개발자들에게 메서드가 의도된 API 레벨을 명확히 알릴 수 있다.
• IDE에서는 @TargetApi 애노테이션이 붙은 메서드에 대해, 사용 중인 API 레벨에 따라 적절한 경고를 제공할 수 있.
• 도입 시기: API 레벨 16 (Jelly Bean)부터.

import android.annotation.TargetApi
import android.os.Build
import android.widget.Toast
import android.content.Context

class ApiLevelExample(private val context: Context) {

    // 이 메서드는 API 레벨 21 (Lollipop) 이상에서만 동작하도록 설계됨
    @TargetApi(Build.VERSION_CODES.LOLLIPOP)
    fun showToastWithNewFeature() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
            // API 레벨 21 이상에서만 사용할 수 있는 기능
            Toast.makeText(context, "This feature is available on API 21 and above", Toast.LENGTH_LONG).show()
        } else {
            // API 레벨 21 이하에서도 실행 가능한 기본 기능
            Toast.makeText(context, "This feature is not available on this API level", Toast.LENGTH_LONG).show()
        }
    }
}

 

 

런타임에서 실제로 API 레벨을 확인하고, 해당 레벨에서만 특정 기능이 실행되도록 하는 코드를 작성해야 한다. 이 어노테이션 자체가 런타임에서 코드의 실행을 제어하지는 않는다.

1. @TargetApi 어노테이션
   • 이 어노테이션은 메서드에 붙여서, 해당 메서드가 특정 API 레벨 이상에서만 사용된다는 것을 나타낸다.
2. Build.VERSION_CODES.LOLLIPOP:
   • Build.VERSION_CODES.LOLLIPOP은 API 레벨 21을 의미한다.
   • 이 상수는 안드로이드 SDK에서 제공하며, 현재 기기의 API 레벨과 비교하는 데 사용된다.
3. showToastWithNewFeature() 메서드:
   • 이 메서드는 API 레벨 21 이상의 기기에서만 동작하는 기능을 제공한다.
   • API 레벨 21 이하에서는 해당 기능을 사용할 수 없음을 사용자에게 알리는 메시지를 표시한다.