# 厂商定制接口规范

## 概述

厂商定制接口是Android系统定制化开发中的重要内容，本文档介绍厂商定制接口的设计规范、版本管理、兼容性等。

## 接口设计原则

### 1. 设计原则

#### 兼容性原则
- 保持向后兼容
- 避免破坏性变更
- 提供迁移路径

#### 可扩展性原则
- 接口设计灵活
- 支持功能扩展
- 预留扩展空间

#### 稳定性原则
- 接口稳定可靠
- 充分测试验证
- 文档完善

### 2. 接口分类

#### 系统服务接口
- 系统级服务接口
- 需要系统权限
- 通过Binder通信

#### 应用接口
- 应用可用的接口
- 通过API提供
- 权限控制

#### 隐藏接口
- 系统内部接口
- 不对外公开
- 使用@hide标记

## 接口定义规范

### 1. AIDL接口定义

#### 接口文件规范
```java
// IVendorCustomService.aidl
package com.android.vendor;

/**
 * 厂商定制服务接口
 * @version 1.0
 * @since Android 10
 */
interface IVendorCustomService {
    /**
     * 获取定制数据
     * @return 定制数据
     */
    String getCustomData();
    
    /**
     * 设置定制数据
     * @param data 定制数据
     * @return 操作结果，0表示成功
     */
    int setCustomData(String data);
    
    /**
     * 执行定制操作
     * @param operation 操作类型
     * @param params 操作参数
     * @return 操作结果
     */
    Bundle performCustomOperation(int operation, Bundle params);
}
```

#### 接口命名规范
- 使用描述性名称
- 遵循Java命名规范
- 使用前缀区分（如Vendor）

### 2. Java接口定义

#### 接口类定义
```java
/**
 * 厂商定制接口
 * @hide
 */
public interface IVendorCustomInterface {
    /**
     * 获取版本号
     * @return 接口版本号
     */
    int getVersion();
    
    /**
     * 检查功能是否支持
     * @param feature 功能ID
     * @return 是否支持
     */
    boolean isFeatureSupported(int feature);
    
    /**
     * 执行功能
     * @param feature 功能ID
     * @param params 参数
     * @return 执行结果
     */
    boolean executeFeature(int feature, Bundle params);
}
```

### 3. 接口实现

#### 服务实现
```java
/**
 * 厂商定制服务实现
 * @hide
 */
public class VendorCustomService extends IVendorCustomService.Stub {
    private static final String TAG = "VendorCustomService";
    private static final int VERSION = 1;
    
    @Override
    public String getCustomData() {
        // 权限检查
        enforceVendorPermission();
        // 实现逻辑
        return getData();
    }
    
    @Override
    public int setCustomData(String data) {
        enforceVendorPermission();
        // 实现逻辑
        return setData(data);
    }
    
    private void enforceVendorPermission() {
        // 检查调用者权限
        if (Binder.getCallingUid() != Process.SYSTEM_UID) {
            throw new SecurityException("Vendor permission required");
        }
    }
}
```

## 接口版本管理

### 1. 版本号规范

#### 版本号格式
- **主版本号**: 不兼容的变更
- **次版本号**: 兼容的功能添加
- **修订版本号**: 兼容的问题修复

#### 版本号示例
```
1.0.0  # 初始版本
1.1.0  # 添加新功能
1.1.1  # 修复问题
2.0.0  # 不兼容变更
```

### 2. 版本兼容性

#### 向后兼容
- 新版本保持旧接口
- 不删除已有接口
- 不修改接口签名

#### 兼容性处理
```java
public class VendorCustomService extends IVendorCustomService.Stub {
    private static final int CURRENT_VERSION = 2;
    
    @Override
    public int getVersion() {
        return CURRENT_VERSION;
    }
    
    // 保持旧接口
    @Override
    public String getCustomData() {
        return getCustomDataV2(null);
    }
    
    // 新接口
    public String getCustomDataV2(Bundle options) {
        // 新实现
    }
}
```

### 3. 版本迁移

#### 迁移策略
- 提供迁移指南
- 保持旧接口一段时间
- 逐步迁移到新接口

#### 迁移示例
```java
/**
 * @deprecated 使用 getCustomDataV2 替代
 */
@Deprecated
public String getCustomData() {
    // 调用新接口
    return getCustomDataV2(null);
}
```

## 接口文档

### 1. 接口文档规范

#### 文档内容
- 接口概述
- 方法说明
- 参数说明
- 返回值说明
- 异常说明
- 使用示例

#### 文档示例
```java
/**
 * 厂商定制服务接口
 * 
 * <p>提供厂商定制功能的服务接口，包括数据获取、设置等功能。</p>
 * 
 * <p>使用示例：</p>
 * <pre>
 * IVendorCustomService service = VendorCustomServiceManager.getService();
 * String data = service.getCustomData();
 * </pre>
 * 
 * @version 1.0
 * @since Android 10
 * @hide
 */
public interface IVendorCustomService {
    /**
     * 获取定制数据
     * 
     * <p>获取系统存储的定制数据，如果数据不存在返回默认值。</p>
     * 
     * @return 定制数据字符串，如果不存在返回"default"
     * @throws RemoteException 如果服务调用失败
     */
    String getCustomData() throws RemoteException;
}
```

### 2. API文档生成

#### 使用javadoc
```bash
# 生成API文档
javadoc -d docs -sourcepath src com.android.vendor
```

## 接口测试

### 1. 单元测试

#### 测试接口功能
```java
@Test
public void testGetCustomData() {
    VendorCustomService service = new VendorCustomService(mockContext);
    String data = service.getCustomData();
    assertNotNull(data);
}

@Test
public void testSetCustomData() {
    VendorCustomService service = new VendorCustomService(mockContext);
    int result = service.setCustomData("test");
    assertEquals(0, result);
}
```

### 2. 集成测试

#### 测试服务调用
```java
@Test
public void testServiceCall() {
    IVendorCustomService service = VendorCustomServiceManager.getService();
    assertNotNull(service);
    
    String data = service.getCustomData();
    assertNotNull(data);
}
```

### 3. 兼容性测试

#### 测试版本兼容
```java
@Test
public void testVersionCompatibility() {
    IVendorCustomService service = VendorCustomServiceManager.getService();
    int version = service.getVersion();
    
    // 测试不同版本的兼容性
    if (version >= 2) {
        // 使用新接口
        String data = service.getCustomDataV2(null);
    } else {
        // 使用旧接口
        String data = service.getCustomData();
    }
}
```

## 接口使用规范

### 1. 客户端使用

#### 获取服务
```java
public class VendorCustomClient {
    private IVendorCustomService mService;
    
    public VendorCustomClient() {
        mService = VendorCustomServiceManager.getService();
    }
    
    public String getCustomData() {
        if (mService == null) {
            return "default";
        }
        try {
            return mService.getCustomData();
        } catch (RemoteException e) {
            Log.e(TAG, "Failed to get custom data", e);
            return "default";
        }
    }
}
```

### 2. 错误处理

#### 异常处理
```java
try {
    String data = service.getCustomData();
    // 处理数据
} catch (RemoteException e) {
    // 服务调用失败
    Log.e(TAG, "Service call failed", e);
    handleError();
} catch (SecurityException e) {
    // 权限不足
    Log.e(TAG, "Permission denied", e);
    requestPermission();
}
```

### 3. 权限检查

#### 权限验证
```java
// 检查权限
if (checkSelfPermission("android.permission.USE_VENDOR_SERVICE") 
        != PackageManager.PERMISSION_GRANTED) {
    // 请求权限
    requestPermission();
    return;
}

// 使用服务
useService();
```

## 接口扩展

### 1. 功能扩展

#### 添加新方法
```java
// 在接口中添加新方法
public interface IVendorCustomService {
    // 原有方法
    String getCustomData();
    
    // 新增方法
    String getCustomDataV2(Bundle options);
}
```

### 2. 参数扩展

#### 使用Bundle扩展
```java
// 使用Bundle支持参数扩展
public Bundle performOperation(int operation, Bundle params) {
    // 支持参数扩展
    if (params != null) {
        // 处理扩展参数
    }
    // 执行操作
}
```

## 最佳实践

### 1. 接口设计
- 接口设计清晰
- 职责单一
- 易于使用

### 2. 版本管理
- 保持向后兼容
- 版本号规范
- 迁移指南

### 3. 文档完善
- 接口文档完整
- 使用示例清晰
- 更新及时

### 4. 测试充分
- 单元测试
- 集成测试
- 兼容性测试

## 相关链接

- [[README]]
- [[系统服务添加流程]]
- [[05-进程与线程通信/AIDL与HIDL使用与原理]]