三方接口設(shè)計(jì)是實(shí)現(xiàn)系統(tǒng)功能的關(guān)鍵環(huán)節(jié)。設(shè)計(jì)一個(gè)安全、高效且易于維護(hù)的接口調(diào)用方案，對(duì)于保障系統(tǒng)穩(wěn)定性、數(shù)據(jù)安全性和用戶體驗(yàn)至關(guān)重要。

一、接口設(shè)計(jì)的基本原則

1. 安全性：確保接口數(shù)據(jù)的安全性，防止數(shù)據(jù)篡改、過期、重復(fù)提交等問題。

2. 可靠性：接口應(yīng)具備高可用性，能夠在高并發(fā)、高負(fù)載環(huán)境下穩(wěn)定運(yùn)行。

3. 易用性：接口設(shè)計(jì)應(yīng)簡(jiǎn)潔明了，易于第三方系統(tǒng)調(diào)用和維護(hù)。

4. 可擴(kuò)展性：接口設(shè)計(jì)應(yīng)考慮到未來的擴(kuò)展需求，便于增加新功能或調(diào)整現(xiàn)有功能。

二、設(shè)計(jì)方案

1. API密鑰生成與管理

• AK（Access Key）：用于標(biāo)識(shí)應(yīng)用，是公開的信息，主要用于標(biāo)示用戶或應(yīng)用身份。

• SK（Secret Key）：加密認(rèn)證密鑰，必須嚴(yán)格保密。通過AK和SK的組合使用，進(jìn)行請(qǐng)求的加密驗(yàn)證，確保請(qǐng)求發(fā)送者的身份合法性。

2. 接口鑒權(quán)機(jī)制

• 客戶端簽名：客戶端使用AK和請(qǐng)求參數(shù)（包括但不限于路徑、方法、參數(shù)、時(shí)間戳等）生成簽名，并將該簽名放入請(qǐng)求頭中，以進(jìn)行身份驗(yàn)證。

• 時(shí)間戳：每個(gè)請(qǐng)求都需附帶當(dāng)前時(shí)間的時(shí)間戳，用于校驗(yàn)請(qǐng)求的時(shí)效性，通常有效期設(shè)置為5分鐘以內(nèi)。

• 流水號(hào)（Nonce）：每個(gè)請(qǐng)求生成一個(gè)唯一的臨時(shí)隨機(jī)數(shù)，確保在有效期內(nèi)不允許重復(fù)提交，防止重復(fù)攻擊。

3. 回調(diào)地址設(shè)置

• 第三方應(yīng)用回調(diào)地址：要求第三方應(yīng)用提供回調(diào)地址，用于接收異步通知和回調(diào)結(jié)果，確保數(shù)據(jù)交互的可靠性和及時(shí)性。

4. 接口API設(shè)計(jì)

• URL設(shè)計(jì)：明確接口的地址結(jié)構(gòu)，便于第三方系統(tǒng)調(diào)用。

• HTTP方法：規(guī)定使用GET、POST、PUT、DELETE等HTTP方法，明確各方法的用途和適用場(chǎng)景。

• 請(qǐng)求參數(shù)：詳細(xì)列出每個(gè)接口所需的請(qǐng)求參數(shù)，包括必填項(xiàng)和可選項(xiàng)，以及參數(shù)的類型和格式。

• 響應(yīng)格式：統(tǒng)一接口響應(yīng)的數(shù)據(jù)格式，如JSON，并明確響應(yīng)中的字段含義和數(shù)據(jù)類型。

5. 權(quán)限劃分與認(rèn)證

• appId：應(yīng)用的唯一標(biāo)識(shí)，用于標(biāo)識(shí)開發(fā)者賬號(hào)或應(yīng)用實(shí)例。

• appKey：公開的密鑰，相當(dāng)于賬號(hào)，用于在請(qǐng)求中標(biāo)識(shí)應(yīng)用身份。

• appSecret：私密密鑰，相當(dāng)于密碼，用于加密和權(quán)限控制。

• token：臨時(shí)令牌，具有時(shí)效性，用于驗(yàn)證用戶或應(yīng)用的身份。在首次驗(yàn)證（如登錄場(chǎng)景）時(shí)，使用appKey和appSecret申請(qǐng)accessToken，并設(shè)置失效時(shí)間。后續(xù)每次請(qǐng)求都需帶上該token以表明權(quán)限通過。

6. appKey + appSecret機(jī)制

• 首次驗(yàn)證：在首次驗(yàn)證時(shí)，使用appKey和appSecret來申請(qǐng)accessToken，該token帶有失效時(shí)間，用于后續(xù)的請(qǐng)求認(rèn)證。

• 權(quán)限控制：針對(duì)同一業(yè)務(wù)的不同權(quán)限需求（如只讀權(quán)限和讀寫權(quán)限），可通過分配不同的appKey和appSecret來實(shí)現(xiàn)權(quán)限劃分。每個(gè)appKey和appSecret對(duì)應(yīng)不同的權(quán)限級(jí)別。

7. 簡(jiǎn)化場(chǎng)景

• 開放性接口：如百度、谷歌地圖API等，可省去appId和appKey，將三者合一（appId = appKey = appSecret），此時(shí)appId主要用于統(tǒng)計(jì)用戶調(diào)用接口的次數(shù)。

• 單一權(quán)限配置：當(dāng)每個(gè)用戶有且僅有一套權(quán)限配置時(shí)，可去掉appKey，直接使用appId和appSecret進(jìn)行身份認(rèn)證和權(quán)限控制。

• 簽名驗(yàn)證：在調(diào)用方向服務(wù)提供方發(fā)起請(qǐng)求時(shí)，帶上（appKey、時(shí)間戳timeStamp、隨機(jī)數(shù)nonce、簽名sign）。簽名sign可使用（AppSecret + 時(shí)間戳 + 隨機(jī)數(shù)）通過sha1、md5等算法生成。服務(wù)提供方收到請(qǐng)求后，生成本地簽名并與收到的簽名進(jìn)行比對(duì)，一致則校驗(yàn)成功。

8. 簽名字段說明

• appId和appSecret：唯一標(biāo)識(shí)和密鑰，為不同的調(diào)用方分配不同的appId和appSecret。

• 時(shí)間戳（timeStamp）：以服務(wù)端當(dāng)前時(shí)間為準(zhǔn)，設(shè)置有效期（如5分鐘以內(nèi)），用于校驗(yàn)請(qǐng)求的時(shí)效性。

• 流水號(hào)（nonce）：臨時(shí)隨機(jī)數(shù)，確保在有效期內(nèi)不允許重復(fù)提交，防止重復(fù)攻擊。

• 簽名字段（sign）：客戶端傳遞的簽名信息，包含appId和sign字段，用于驗(yàn)證身份和防止參數(shù)篡改。服務(wù)提供方通過驗(yàn)證簽名來確保請(qǐng)求的安全性和合法性。

三、接口設(shè)計(jì)的具體步驟

1. API密鑰生成與管理

• 生成密鑰：使用隨機(jī)字符串或UUID生成AK和SK，確保密鑰的唯一性和安全性。

• 存儲(chǔ)密鑰：將生成的AK和SK存儲(chǔ)在數(shù)據(jù)庫(kù)或其他持久化存儲(chǔ)中，便于管理和查詢。

• 分發(fā)密鑰：通過界面、API或自助注冊(cè)流程向第三方系統(tǒng)提供AK和SK。

• 定期輪換密鑰：定期更換SK，以減少密鑰泄露的風(fēng)險(xiǎn)。

// 生成API密鑰

public class ApiKeyGenerator {

    public static String generateAccessKey() {

        return UUID.randomUUID().toString();

    }

    public static String generateSecretKey() {

        return Base64.getEncoder().encodeToString(new byte[16]);

    }

}

2. 接口鑒權(quán)

接口鑒權(quán)是驗(yàn)證請(qǐng)求合法性的重要環(huán)節(jié)。可通過以下方式進(jìn)行鑒權(quán)：

• 簽名驗(yàn)證：客戶端使用AK和請(qǐng)求參數(shù)生成簽名，并在請(qǐng)求頭中攜帶簽名信息。服務(wù)端接收請(qǐng)求后，驗(yàn)證簽名的合法性。

• Token驗(yàn)證：客戶端首次驗(yàn)證時(shí)，使用AK和SK申請(qǐng)Token。后續(xù)請(qǐng)求中攜帶Token，服務(wù)端驗(yàn)證Token的有效性。

// 簽名驗(yàn)證

public class SignAuthInterceptor implements HandlerInterceptor {

    private String secretKey;

    public SignAuthInterceptor(String secretKey) {

        this.secretKey = secretKey;

    }

    @Override

    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {

        String timestamp = request.getHeader("timestamp");

        String nonceStr = request.getHeader("nonceStr");

        String signature = request.getHeader("signature");

        if (isExpired(timestamp) || isNonceUsed(nonceStr)) {

            throw new BusinessException("Invalid request");

        }

        String calculatedSignature = calculateSignature(request, secretKey);

        if (!signature.equals(calculatedSignature)) {

            throw new BusinessException("Invalid signature");

        }

        return true;

    }

    private boolean isExpired(String timestamp) {

        long currentTime = System.currentTimeMillis() / 1000;

        long requestTime = Long.parseLong(timestamp);

        return currentTime - requestTime > 60; // 有效期60秒

    }

    private boolean isNonceUsed(String nonceStr) {

        // 檢查nonceStr是否已使用，可用Redis等存儲(chǔ)

        return false;

    }

    private String calculateSignature(HttpServletRequest request, String secretKey) throws UnsupportedEncodingException {

        Map<String, Object> params = new HashMap<>();

        Enumeration<String> parameterNames = request.getParameterNames();

        while (parameterNames.hasMoreElements()) {

            String name = parameterNames.nextElement();

            String value = request.getParameter(name);

            if (!"signature".equals(name)) {

                params.put(name, URLEncoder.encode(value, "UTF-8"));

            }

        }

        List<String> keys = new ArrayList<>(params.keySet());

        Collections.sort(keys);

        StringBuilder sb = new StringBuilder();

        for (String key : keys) {

            sb.append(key).append("=").append(params.get(key)).append("&");

        }

        sb.append(secretKey);

        return DigestUtils.md5DigestAsHex(sb.toString().getBytes("UTF-8"));

    }

}

3. 接口API設(shè)計(jì)

接口API設(shè)計(jì)包括URL、HTTP方法、請(qǐng)求參數(shù)和響應(yīng)格式等細(xì)節(jié)。設(shè)計(jì)時(shí)應(yīng)遵循RESTful原則，使接口更加簡(jiǎn)潔、易于理解。

• URL設(shè)計(jì)：使用簡(jiǎn)潔、描述性的URL路徑，如/api/resources表示獲取資源列表。

• HTTP方法：使用GET、POST、PUT、DELETE等HTTP方法分別表示不同的操作。

• 請(qǐng)求參數(shù)：明確請(qǐng)求參數(shù)的類型、必填項(xiàng)和默認(rèn)值，便于調(diào)用者理解和使用。

• 響應(yīng)格式：采用統(tǒng)一的響應(yīng)格式，如JSON，包含狀態(tài)碼、消息和數(shù)據(jù)等字段。

// API接口設(shè)計(jì)

@RestController

@RequestMapping("/api/resources")

public class ResourceController {

    @GetMapping

    public Result<List<Resource>> getResources(@RequestParam(defaultValue = "1") int page,

                                               @RequestParam(defaultValue = "10") int limit) {

        // 實(shí)現(xiàn)獲取資源列表的邏輯

        List<Resource> resources = new ArrayList<>();

        return Result.success(resources);

    }

    @PostMapping

    public Result<Resource> createResource(@RequestBody Resource resource) {

        // 實(shí)現(xiàn)創(chuàng)建資源的邏輯

        return Result.success(resource);

    }

    @PutMapping("/{resourceId}")

    public Result<Void> updateResource(@PathVariable String resourceId, @RequestBody Resource resource) {

        // 實(shí)現(xiàn)更新資源的邏輯

        return Result.success();

    }

    @DeleteMapping("/{resourceId}")

    public Result<Void> deleteResource(@PathVariable String resourceId) {

        // 實(shí)現(xiàn)刪除資源的邏輯

        return Result.success();

    }

}

public class Result<T> {

    private int code;

    private String message;

    private T data;

    public static <T> Result<T> success(T data) {

        Result<T> result = new Result<>();

        result.setCode(200);

        result.setMessage("Success");

        result.setData(data);

        return result;

    }

    // 。。。

}

4. 安全性考慮

• 使用HTTPS：保護(hù)數(shù)據(jù)傳輸安全，防止中間人攻擊。

• 請(qǐng)求驗(yàn)簽：服務(wù)端進(jìn)行校驗(yàn)和鑒權(quán)，確保請(qǐng)求的合法性。

• 敏感數(shù)據(jù)加密傳輸：使用TLS加密敏感數(shù)據(jù)，防止數(shù)據(jù)泄露。

• 防止重放攻擊：使用Nonce和Timestamp，確保請(qǐng)求的唯一性和時(shí)效性。

// 防止重放攻擊

public class AntiReplayInterceptor implements HandlerInterceptor {

    private RedisTemplate<String, String> redisTemplate;

    public AntiReplayInterceptor(RedisTemplate<String, String> redisTemplate) {

        this.redisTemplate = redisTemplate;

    }

    @Override

    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {

        String nonceStr = request.getHeader("nonceStr");

        String timestamp = request.getHeader("timestamp");

        if (isNonceUsed(nonceStr) || isExpired(timestamp)) {

            throw new BusinessException("Invalid request");

        }

        return true;

    }

    private boolean isNonceUsed(String nonceStr) {

        return redisTemplate.hasKey(nonceStr);

    }

    private boolean isExpired(String timestamp) {

        long currentTime = System.currentTimeMillis() / 1000;

        long requestTime = Long.parseLong(timestamp);

        return currentTime - requestTime > 60; // 有效期60秒

    }

}

三、接口調(diào)用的最佳實(shí)踐

1. 合理使用Token：使用Token減少用戶名和密碼的傳輸次數(shù)，提高接口調(diào)用的安全性。

2. 錯(cuò)誤處理：在調(diào)用接口時(shí)，應(yīng)妥善處理可能出現(xiàn)的錯(cuò)誤，如網(wǎng)絡(luò)異常、參數(shù)錯(cuò)誤等。

3. 日志記錄：記錄接口調(diào)用的日志，便于問題排查和性能分析。

4. 接口限流：對(duì)接口進(jìn)行限流，防止惡意攻擊或?yàn)E用資源。

原文來源：https://mp.weixin.qq.com/s/xz0wNkpHXuSFx1BZH-RK9g