[JavaScript] axios 初探（一）：基本用法、axios instance 與 URL 編碼處理

axios({
  method: 'get',
  url: 'https://jsonplaceholder.typicode.com/posts/1',
  headers: { 'X-Custom-Header': 'foobar' },
})
  .then(response => console.log(response.data))
  .catch(error => console.error(error))

axios('https://jsonplaceholder.typicode.com/posts/1', {
  headers: { 'X-Custom-Header': 'foobar' },
})
  .then(response => console.log(response.data))
  .catch(error => console.error(error))

axios.get('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

const apiClient = axios.create({
  baseURL: 'https://jsonplaceholder.typicode.com',
  timeout: 5000,
  headers: { 'X-Custom-Header': 'foobar' }
});
apiClient.get('/posts/1').then(res => console.log(res.data));

function createInstance(defaultConfig) {
  const context = new Axios(defaultConfig); //  creates a new Axios instance
  const instance = bind(Axios.prototype.request, context); // creates a bound function using the bind method, This creates a function that will call Axios.prototype.request with the correct this context.

  // Copy axios.prototype to instance
  utils.extend(instance, Axios.prototype, context, { allOwnKeys: true });
  // Copy context to instance
  utils.extend(instance, context, null, { allOwnKeys: true });

  // Factory for creating new instances
  instance.create = function create(instanceConfig) {
    return createInstance(mergeConfig(defaultConfig, instanceConfig));
  };
  return instance; //  instance is both a function AND an object
}

const axios = createInstance(defaults);

// ...
axios.spread = spread;

// Expose isAxiosError
axios.isAxiosError = isAxiosError;

// Expose mergeConfig
axios.mergeConfig = mergeConfig;

axios.AxiosHeaders = AxiosHeaders;
// ..

export interface AxiosStatic extends AxiosInstance {
  create(config?: CreateAxiosDefaults): AxiosInstance;
  Cancel: CancelStatic;
  CancelToken: CancelTokenStatic;
  Axios: typeof Axios;
  AxiosError: typeof AxiosError;
  HttpStatusCode: typeof HttpStatusCode;
  readonly VERSION: string;
  isCancel: typeof isCancel;
  all: typeof all;
  spread: typeof spread;
  isAxiosError: typeof isAxiosError;
  toFormData: typeof toFormData;
  formToJSON: typeof formToJSON;
  getAdapter: typeof getAdapter;
  CanceledError: typeof CanceledError;
  AxiosHeaders: typeof AxiosHeaders;
  mergeConfig: typeof mergeConfig;
}

declare const axios: AxiosStatic;

export interface AxiosInstance extends Axios {
  <T = any, R = AxiosResponse<T>, D = any>(config: AxiosRequestConfig<D>): Promise<R>;
  <T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<R>;

  defaults: Omit<AxiosDefaults, 'headers'> & {
    headers: HeadersDefaults & {
      [key: string]: AxiosHeaderValue
    }
  };
}

const instance1 = axios.create({
  baseURL: 'https://jsonplaceholder.typicode.com',
  timeout: 5000,
  headers: { 'X-Custom-Header': 'foobar' },
})
const instance2 = instance1.create({
  baseURL: 'https://jsonplaceholder.typicode.com',
  timeout: 5000,
  headers: { 'X-Custom-Header': 'foobar' },
})
instance2.get('/posts/1').then(res => console.log(res.data)) // 可順利印出資料

async function axiosParamsInUrl() {
  const search = 'hello world!';
  const symbol = '&$';
  const response = await axios.get(
    `${API_URL}/url-encoded?search=${search}&symbol=${symbol}`
  );
  console.log(response.data);
}

receivedQuery: {
  search: 'hello world!',
  symbol: '',
  $: ''
}

async function axiosAutoEncodeParams() {
  const search = 'hello world!';
  const symbol = '&$';
  const response = await axios.get(`${API_URL}/url-encoded`, {
    params: { search, symbol },
  });
  console.log(response.data);
}

receivedQuery: {
  search: 'hello world!',
  symbol: '&$'
}

async function fetchWithoutEncode() {
  const search = 'hello world!';
  const symbol = '&$';
  const res = await fetch(
    `${API_URL}/url-encoded?search=${search}&symbol=${symbol}`
  );
  const data = await res.json();
  console.log(data);
}

receivedQuery: {
  search: 'hello world!',
  symbol: '',
  $: ''
}

async function fetchManualEncode() {
  const search = 'hello world!';
  const symbol = '&$';
  const res = await fetch(
    `${API_URL}/url-encoded?search=${encodeURIComponent(
        search
      )}&symbol=${encodeURIComponent(symbol)}`
  );
  const data = await res.json();
  console.log(data);
}

receivedQuery: {
  search: 'hello world!',
  symbol: '&$'
}

/**
 * Build a URL by appending params to the end
 *
 * @param {string} url The base of the url (e.g., http://www.google.com)
 * @param {object} [params] The params to be appended
 * @param {?(object|Function)} options
 *
 * @returns {string} The formatted url
 */
export default function buildURL(url, params, options) {
  /*eslint no-param-reassign:0*/
  if (!params) { // 如果沒有提供 params，就直接回傳原本的 URL，這也說明了為何在 axios.get(url) 放上的 params 不會被編碼，要將參數放在 axios config 的 params 欄位內才會編碼
    return url;
  }

  const _encode = options && options.encode || encode; // 如果有傳入 options.encode，就使用它；否則就用內建的 encode 函式

  if (utils.isFunction(options)) { // 如果 options 傳進來是一個函式（例如自訂的 serialize），會把它轉成 { serialize: fn } 格式
    options = {
      serialize: options
    };
  }

  const serializeFn = options && options.serialize;

  let serializedParams;

  if (serializeFn) {
    serializedParams = serializeFn(params, options); // 如果有自訂的 serialize 函式，就使用該 function 處理 params
  } else {
    serializedParams = utils.isURLSearchParams(params) ? // 如果是 URLSearchParams instance，直接呼叫 .toString()，代表開發者已經自己將 params 做好轉換，axios 不用再處理
      params.toString() :
      new AxiosURLSearchParams(params, options).toString(_encode); // 使用 Axios 自己的 AxiosURLSearchParams 類別來處理
  }

  if (serializedParams) { // 如果有序列化後的參數
    const hashmarkIndex = url.indexOf("#"); // 尋找 URL 中的 # 符號位置

    if (hashmarkIndex !== -1) { // 如果找到 # 符號，就移除 # 及其後面的內容
      url = url.slice(0, hashmarkIndex);
    }
    //  根據 URL 是否已有查詢參數來決定使用 ? 或 & 來連接新參數，例如 url 是 https://example.com/search?type=user 就是用 & 繼續加後面的參數
    url += (url.indexOf('?') === -1 ? '?' : '&') + serializedParams;
  }

  return url;
}

/**
 * It takes a params object and converts it to a FormData object
 *
 * @param {Object<string, any>} params - The parameters to be converted to a FormData object.
 * @param {Object<string, any>} options - The options object passed to the Axios constructor.
 *
 * @returns {void}
 */
function AxiosURLSearchParams(params, options) {
  this._pairs = []; // 初始化 key-value pairs
  params && toFormData(params, this, options); // 如果有 params 就呼叫 toFormData，toFormData 會呼叫 append 將 key-pairs 加入 _pairs 陣列
}

const prototype = AxiosURLSearchParams.prototype;

prototype.append = function append(name, value) { // 定義 append 方法，將新的 key-value pair 新增到內部的 pairs 陣列
  this._pairs.push([name, value]);
};

prototype.toString = function toString(encoder) { // 定義 toString 方法，將所有 pairs 轉換為 URL-encoded string
  const _encode = encoder ? function(value) { // 如果 toString 參數有指定 encoder，就回傳此 custom encoder， encoder.call(this, value, encode) 允許 custom encoder 存取要 encode 的 value 和 axios 預設的 encode function
    return encoder.call(this, value, encode);
  } : encode; // 沒有指定 encoder，就使用預設 encode function

  return this._pairs.map(function each(pair) { // 遍歷 pairs 陣列，對每個 pair 操作：Encodes the key (pair[0])、Adds an equals sign (=)、Encodes the value (pair[1])，最後用 & 連接每個 encoded pairs
    return _encode(pair[0]) + '=' + _encode(pair[1]);
  }, '').join('&');
};

/**
 * It encodes a string by replacing all characters that are not in the unreserved set with
 * their percent-encoded equivalents
 *
 * @param {string} str - The string to encode.
 *
 * @returns {string} The encoded string.
 */
function encode(str) {
  const charMap = {
    '!': '%21', // 驚嘆號在某些伺服器可能被解釋為特殊命令
    "'": '%27', // 單引號可能導致 SQL 注入或 XSS 攻擊
    '(': '%28', //  括號在某些查詢語言中有特殊含義
    ')': '%29',
    '~': '%7E', // 波浪號在某些系統中用於表示根目錄
    '%20': '+', // 使用 + 表示空格，是 URL 查詢參數的常見慣例
    '%00': '\x00' // 空字節需要特殊處理以防止安全漏洞
  };
  // 呼叫 encodeURIComponent 做基本編碼，接著針對特定字元再用 charMap 進一步處理
  return encodeURIComponent(str).replace(/[!'()~]|%20|%00/g, function replacer(match) {
    return charMap[match];
  });
}

// 1. 空格的處理
const text1 = "Hello World";
encodeURIComponent(text1)  // Hello%20World
encode(text1)  // Hello+World

// 2. 特殊字元的處理
const text2 = "test!()'~";
encodeURIComponent(text2)  // test!()'~
encode(text2) // test%21%28%29%27%7E

const params = {
  name: 'John Doe',
  age: 30,
};
const serializedParams = new AxiosURLSearchParams(params).toString(_encode);
// serializedParams 會是 "name=John+Doe&age=30"

const {toString} = Object.prototype;
const kindOf = (cache => thing => {
    const str = toString.call(thing);
    return cache[str] || (cache[str] = str.slice(8, -1).toLowerCase());
})(Object.create(null));

// 當我們呼叫 isURLSearchParams 時...
const params = new URLSearchParams();
isURLSearchParams(params);

// 內部發生的過程：
// 1. toString.call(params) 回傳 "[object URLSearchParams]"
// 2. slice(8, -1) 得到 "URLSearchParams"
// 3. toLowerCase() 得到 "urlsearchparams"
// 4. 與傳入的 type 比較，回傳 true

const arr = [1, 2, 3];
arr.toString()  // 回傳 "1,2,3"

const date = new Date();
date.toString()  // 回傳像 "Mon Jan 01 2024 12:00:00 GMT+0800" 這樣的字串

// 使用 call
Object.prototype.toString.call([1, 2, 3])     // "[object Array]"
Object.prototype.toString.call(new Date())    // "[object Date]"
Object.prototype.toString.call(new URLSearchParams()) // "[object URLSearchParams]"

// 直接呼叫 toString
[1, 2, 3].toString()      // "1,2,3"
new Date().toString()     // "Mon Jan 01 2024 12:00:00 GMT+0800"

// 在 iframe 情境
const iframe = document.createElement('iframe');
document.body.appendChild(iframe);
const iframeArray = iframe.contentWindow.Array;
const arr = new iframeArray();

// Object.prototype.toString.call()
toString.call(arr)  // '[object Array]' → 正確識別

// instanceof
arr instanceof Array  // false → 無法正確識別跨域物件

// Object.prototype.toString.call()
toString.call('string')  // '[object String]'
toString.call(123)      // '[object Number]'
toString.call(true)     // '[object Boolean]'

// instanceof
'string' instanceof String  // false
123 instanceof Number      // false
true instanceof Boolean    // false

// Object.prototype.toString.call()
toString.call(null)      // '[object Null]'
toString.call(undefined) // '[object Undefined]'

// instanceof
null instanceof Object    // false
undefined instanceof Object // false

// 兩種方法都可行
const formData = new FormData();
const blob = new Blob([]);
const arrayBuffer = new ArrayBuffer(8);

// 方法 1: Object.prototype.toString.call()
toString.call(formData)    // '[object FormData]'
toString.call(blob)        // '[object Blob]'
toString.call(arrayBuffer) // '[object ArrayBuffer]'

// 方法 2: instanceof
formData instanceof FormData       // true
blob instanceof Blob               // true
arrayBuffer instanceof ArrayBuffer // true

// 在 iframe 中
const iframe = document.createElement('iframe');
document.body.appendChild(iframe);
const iframeFormData = new iframe.contentWindow.FormData();

// Object.prototype.toString.call() - 可運作
toString.call(iframeFormData) === '[object FormData]'  // true

// instanceof - 可能失敗
iframeFormData instanceof FormData  // 在某些瀏覽器中會是 false