{"id":19765701,"url":"https://github.com/xuexiangjys/xtask","last_synced_at":"2025-04-30T15:30:41.022Z","repository":{"id":37702052,"uuid":"415392228","full_name":"xuexiangjys/XTask","owner":"xuexiangjys","description":"一个拓展性极强的Android任务执行框架。可自由定义和组合任务来实现你想要的功能，尤其适用于处理复杂的业务流程，可灵活添加前置任务或者调整执行顺序。例如：应用的启动初始化流程。","archived":false,"fork":false,"pushed_at":"2024-03-12T15:03:52.000Z","size":1197,"stargazers_count":139,"open_issues_count":3,"forks_count":26,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-03-12T16:29:56.926Z","etag":null,"topics":["android","task-manager","task-runner","x-library"],"latest_commit_sha":null,"homepage":"https://github.com/xuexiangjys/XTask/wiki","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xuexiangjys.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"custom":"https://gitee.com/xuexiangjys/Resource/blob/master/doc/sponsor.md"}},"created_at":"2021-10-09T18:35:22.000Z","updated_at":"2024-03-12T16:29:56.927Z","dependencies_parsed_at":"2024-02-14T03:41:20.718Z","dependency_job_id":null,"html_url":"https://github.com/xuexiangjys/XTask","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuexiangjys%2FXTask","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuexiangjys%2FXTask/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuexiangjys%2FXTask/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuexiangjys%2FXTask/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xuexiangjys","download_url":"https://codeload.github.com/xuexiangjys/XTask/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224214832,"owners_count":17274690,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","task-manager","task-runner","x-library"],"created_at":"2024-11-12T04:19:10.988Z","updated_at":"2024-11-12T04:19:11.580Z","avatar_url":"https://github.com/xuexiangjys.png","language":"Java","funding_links":["https://gitee.com/xuexiangjys/Resource/blob/master/doc/sponsor.md"],"categories":[],"sub_categories":[],"readme":"# XTask\n[![](https://jitpack.io/v/xuexiangjys/XTask.svg)](https://jitpack.io/#xuexiangjys/XTask)\n[![api](https://img.shields.io/badge/API-14+-brightgreen.svg)](https://android-arsenal.com/api?level=14)\n[![I](https://img.shields.io/github/issues/xuexiangjys/XTask.svg)](https://github.com/xuexiangjys/XTask/issues)\n[![Star](https://img.shields.io/github/stars/xuexiangjys/XTask.svg)](https://github.com/xuexiangjys/XTask)\n\n一个拓展性极强的Android任务执行框架。可自由定义和组合任务来实现你想要的功能，尤其适用于处理复杂的业务流程，可灵活添加前置任务或者调整执行顺序。例如：应用的启动初始化流程。\n\n在使用前，请一定要仔细阅读[使用说明文档](https://github.com/xuexiangjys/XTask/wiki),重要的事情说三遍！！！\n\n在使用前，请一定要仔细阅读[使用说明文档](https://github.com/xuexiangjys/XTask/wiki),重要的事情说三遍！！！\n\n在使用前，请一定要仔细阅读[使用说明文档](https://github.com/xuexiangjys/XTask/wiki),重要的事情说三遍！！！\n\n## 关于我\n\n| 公众号   | 掘金     |  知乎    |  CSDN   |   简书   |   思否  |   哔哩哔哩  |   今日头条\n|---------|---------|--------- |---------|---------|---------|---------|---------|\n| [我的Android开源之旅](https://t.1yb.co/Irse)  |  [点我](https://juejin.im/user/598feef55188257d592e56ed/posts)    |   [点我](https://www.zhihu.com/people/xuexiangjys/posts)       |   [点我](https://xuexiangjys.blog.csdn.net/)  |   [点我](https://www.jianshu.com/u/6bf605575337)  |   [点我](https://segmentfault.com/u/xuexiangjys)  |   [点我](https://space.bilibili.com/483850585)  |   [点我](https://img.rruu.net/image/5ff34ff7b02dd)\n\n## X系列库快速集成\n\n为了方便大家快速集成X系列框架库，我提供了一个空壳模版供大家参考使用: https://github.com/xuexiangjys/TemplateAppProject\n\n除此之外，我还特别制作了几期[X系列视频教程](https://space.bilibili.com/483850585/channel/detail?cid=104998)供大家学习参考.\n\n---\n\n## 特征\n\n* 支持6种线程类型方式执行任务。\n* 支持任务链中各任务的执行线程调度和控制。\n* 支持快捷任务创建，同时支持自定义任务。\n* 支持串行和并行等组任务。\n* 支持任务间数据共享。\n* 支持自由组合任务执行。\n* 支持任务链执行取消。\n* 支持取消所有任务链和指定名称的任务链。\n* 支持任务链调用顺序记录和查询。\n* 支持自定义任务执行的线程池。\n\n## 组成结构\n\n* 任务链`ITaskChainEngine`：任务链执行引擎，负责统筹调度各任务步骤。\n\n* 任务步骤`ITaskStep`：负责具体任务逻辑处理。\n\n* 数据存储仓库`IDataStore`：存放数据的仓库，主要用于保存任务参数中的数据。\n\n* 任务参数`ITaskParam`：负责任务路径记录以及任务产生的参数管理。\n\n* 任务执行结果`ITaskResult`：存放任务最终执行的结果以及产生的数据。\n\n* 任务组`IGroupTaskStep`：负责统筹调度各子任务步骤。\n\n[点击查看框架UML设计图](https://github.com/xuexiangjys/XTask/blob/master/art/xtask_uml.png)\n\n## 日志一览\n\n![task_log.png](https://s4.ax1x.com/2022/02/16/HWdTHJ.png)\n\n![task_log2.png](https://s4.ax1x.com/2022/02/16/HWwnbQ.png)\n\n---\n\n## 集成指南\n\n### 添加Gradle依赖\n\n1.先在项目根目录的 `build.gradle` 的 `repositories` 添加:\n\n```\nallprojects {\n     repositories {\n        ...\n        maven { url \"https://jitpack.io\" }\n    }\n}\n```\n\n2.然后在应用项目(一般是app)的 `build.gradle` 的 dependencies 添加:\n\n```\ndependencies {\n  ...\n  // XTask\n  implementation 'com.github.xuexiangjys.XTask:xtask-core:1.0.2'\n}\n```\n\n## 使用方法\n\n\u003e [XTask](https://github.com/xuexiangjys/XTask/blob/master/xtask-core/src/main/java/com/xuexiang/xtask/XTask.java)作为对外统一的API入口，所有常用的方法都能从中找到。\n\n### 打开调试模式\n\n当需要定位问题，需要进行调试时，可打开调试模式，这样便可开启框架的日志。\n\n```\nXTask.debug(true);\n```\n\n### XTask的API介绍\n\n方法名\t| 描述\n|---|---\ndebug | 设置是否打开调试\nsetLogger | 自定义日志打印\nsetIsLogThreadName | 设置是否打印任务执行所在的线程名，默认false\ngetTaskChain | 获取任务链执行引擎\ngetTask | 获取简化的任务\ngetTaskBuilder | 获取简化任务的构建者\ngetConcurrentGroupTask | 获取并行任务组\ngetSerialGroupTask | 获取串行任务组\ncancelTaskChain | 取消指定任务链执行\ncancelAllTaskChain | 取消所有任务链执行\npostToMain | 执行任务到主线程\npostToMainDelay | 延迟执行任务到主线程\nsubmit | 执行普通异步任务\nemergentSubmit | 执行紧急异步任务\nbackgroundSubmit | 执行后台异步任务\nioSubmit | 执行io耗时的异步任务\ngroupSubmit | 执行分组异步任务\nschedule | 执行延期任务\nscheduleAtFixedRate | 执行周期任务（固定间期）\nscheduleWithFixedDelay | 执行周期任务（固定延期）\n\n### 如何执行一条任务链\n\n下面是一整个完整的例子：\n\n```\n// 1.创建一条任务链（必须）\nfinal TaskChainEngine engine = XTask.getTaskChain();\n// 2.设置任务链的初始化参数（可选）\nengine.setTaskParam(TaskParam.get(\"chainName\", engine.getName()));\nTaskParam taskParam = TaskParam.get(\"param1\", 100)\n        .put(\"param2\", true);\n// 3.创建多个任务，并向任务链中添加（必须）\nXTaskStep taskStep = XTask.getTask(new TaskCommand() {\n    @Override\n    public void run() {\n        ITaskParam param = getTaskParam();\n        Log.e(TAG, getName() + \"  start, param1:\" + param.get(\"param1\") + \", chainName:\" + param.get(\"chainName\"));\n        param.put(\"param1\", 200);\n        param.put(\"param3\", \"this is param3!\");\n    }\n}, taskParam);\nengine.addTask(taskStep)\n        .addTask(XTask.getTask(new TaskCommand() {\n            @Override\n            public void run() {\n                ITaskParam param = getTaskParam();\n                Log.e(TAG, getName() + \"  start, param1:\" + param.get(\"param1\") + \", param3:\" + param.get(\"param3\"));\n                param.put(\"param2\", false);\n            }\n        }));\n// 4.设置任务链执行回调（可选）\nICanceller canceller = engine.setTaskChainCallback(new TaskChainCallbackAdapter() {\n    @Override\n    public void onTaskChainCompleted(@NonNull ITaskChainEngine engine, @NonNull ITaskResult result) {\n        Log.e(TAG, \"task chain completed, thread:\" + Thread.currentThread().getName());\n        Map\u003cString, Object\u003e data = result.getDataStore().getData();\n        for (Map.Entry\u003cString, Object\u003e entry : data.entrySet()) {\n            Log.e(TAG, \"key:\" + entry.getKey() + \", value:\" + entry.getValue());\n        }\n    }\n// 5.任务链执行（必须）\n}).start();\n```\n\n1.创建一条任务链.（必须）\n\n```\nTaskChainEngine engine = XTask.getTaskChain();\n```\n\n2.设置任务链的初始化参数.（可选）\n\n```\nengine.setTaskParam(TaskParam.get(\"chainName\", engine.getName()));\n```\n\n3.创建多个任务，并向任务链中添加.（必须）\n\n```\n// 设置任务初始化参数\nTaskParam taskParam = TaskParam.get(\"param1\", 100)\n        .put(\"param2\", true);\nXTaskStep taskStep = XTask.getTask(new TaskCommand() {\n    @Override\n    public void run() {\n        // ...执行任务\n    }\n}, taskParam);\nengine.addTask(taskStep)\n        .addTask(XTask.getTask(new TaskCommand() {\n            @Override\n            public void run() {\n                // ...执行任务\n            }\n        }));\n```\n\n【注意】对于任务执行完成，需要注意以下两点：\n\n* 如果任务执行成功，就调用`notifyTaskSucceed`，任务执行失败，就调用`notifyTaskFailed`。这里任务无论成功还是失败，只要执行完成都需要调用`notifyTaskXXX`通知任务链该任务完成，否则任务将无法正常执行。\n* `TaskCommand`和`SimpleTaskStep`默认提供了自动通知执行结果的功能，但是AbstractTaskStep没有提供，需要手动通知。\n\n4.设置任务链执行回调.（可选）\n\n调用setTaskChainCallback设置任务链执行回调。\n\n```\nengine.setTaskChainCallback(new TaskChainCallbackAdapter() {\n\n    @Override\n    public boolean isCallBackOnMainThread() {\n        // 回调是否返回主线程, 默认是true\n        return false;\n    }\n    @Override\n    public void onTaskChainStart(@NonNull ITaskChainEngine engine) {\n        Log.e(TAG, \"task chain start\");\n    }\n    @Override\n    public void onTaskChainCompleted(@NonNull ITaskChainEngine engine, @NonNull ITaskResult result) {\n        Log.e(TAG, \"task chain completed, thread:\" + Thread.currentThread().getName());\n    }\n    @Override\n    public void onTaskChainError(@NonNull ITaskChainEngine engine, @NonNull ITaskResult result) {\n        Log.e(TAG, \"task chain error\");\n    }\n})\n```\n\n5.任务链执行.（必须）\n\n调用start执行任务链。\n\n```\nICanceller canceller = engine.start();\n```\n\n## 任务创建\n\n创建任务有两种方式：\n\n* 通过XTask.getTask构建\n* 继承`SimpleTaskStep`/`AbstractTaskStep`实现任务的自定义\n\n### 通过XTask创建\n\n\u003e 通过XTask.getTask, 传入对应的属性进行构建\n\n属性名\t| 描述\t| 默认值\n|---|---|---\nname | 任务步骤名称 | XTaskStep-N(N为自增数）\ncommand | 任务执行内容 | /\nthreadType | 线程执行类型  | ThreadType.ASYNC\ntaskParam | 任务参数 | new TaskParam()\ntaskHandler | 任务处理者 | null\nisAutoNotify | 是否自动通知任务执行结果 | true\n```\nXTaskStep taskStep = XTask.getTask(new TaskCommand() {\n    @Override\n    public void run() {\n        // todo\n    }\n}, ThreadType.ASYNC, taskParam);\n```\n\n### 通过继承创建\n\n\u003e 通过继承`SimpleTaskStep`或者`AbstractTaskStep`实现具体功能。\n\n```\npublic class StepATask extends SimpleTaskStep {\n\n    @Override\n    public void doTask() throws Exception {\n        // todo\n        // 不需要手动通知任务链任务完成\n    }\n}\n\npublic class StepBTask extends AbstractTaskStep {\n\n    @Override\n    public void doTask() throws Exception {\n        // todo\n        // 需手动通知任务链任务完成\n        notifyTaskSucceed(TaskResult.succeed());\n    }\n\n    @Override\n    public String getName() {\n        return \"StepATask\";\n    }\n}\n```\n\n## 任务执行原则\n\n每一个任务都是依托于任务链进行流程控制。任何任务都需要遵循以下原则：\n\n* 任何任务无论失败还是成功，都需要调用`notifyTaskSucceed`或者`notifyTaskFailed`去通知任务链任务的完成情况。`TaskCommand`和`SimpleTaskStep`默认提供了自动通知执行结果的功能。\n* 一旦任务链中某个任务执行失败，整个链路都停止工作。\n\n任务类型\t| 任务执行说明\n|---|---\nTaskCommand | 自动通知执行结果。如需手动通知，只需设置`isAutoNotify`为false即可\nSimpleTaskStep | 自动通知执行结果。如需手动通知，只需重写`isAutoNotify`方法为false即可\nAbstractTaskStep | 需手动通知执行结果\n\n### TaskCommand手动通知执行结果\n\n在通过XTask.getTask传入TaskCommand构建Task的时候，设置`isAutoNotify`为false即可手动通知执行结果。\n\n```\nfinal TaskChainEngine engine = XTask.getTaskChain();\nfor (int i = 0; i \u003c 5; i++) {\n    int finalI = i;\n    engine.addTask(XTask.getTask(new TaskCommand() {\n        @Override\n        public void run() {\n            try {\n                Thread.sleep(1000);\n            } catch (InterruptedException e) {\n                e.printStackTrace();\n            }\n            if (finalI == 2) {\n                notifyTaskFailed(404, \"任务执行失败!\");\n            } else {\n                notifyTaskSucceed(TaskResult.succeed());\n            }\n        }\n    }, false)); // 设置手动通知执行结果\n}\nengine.start();\n```\n\n### SimpleTaskStep手动通知执行结果\n\n重写`SimpleTaskStep`的`isAutoNotify`方法为false即可手动通知执行结果。\n\n```\npublic class StepATask extends SimpleTaskStep {\n\n    @Override\n    public void doTask() throws Exception {\n        // todo\n        // 手动通知任务链任务完成\n        notifyTaskSucceed();\n    }\n\n    @Override\n    protected boolean isAutoNotify() {\n        return false;\n    }\n}\n```\n\n## 参数传递\n\n* 任何TaskStep我们都可以通过`getTaskParam`获取任务参数和任务执行结果`ITaskParam`。\n* 上一个TaskStep保存处理过的任务参数会自动带入到下一个TaskStep中去，因此最后一个TaskStep拥有之前所有任务的参数数据。\n\n```\nXTask.getTask(new TaskCommand() {\n    @Override\n    public void run() {\n        ITaskParam param = getTaskParam();\n        Log.e(TAG, getName() + \"  start, param1:\" + param.get(\"param1\") + \", param3:\" + param.get(\"param3\"));\n        param.put(\"param2\", false);\n    }\n})\n```\n\n## 线程控制\n\n设置任务的threadType类型，即可完成对任务运行线程的控制。目前支持6种线程处理方式。\n\n类型\t| 描述 | 线程池构成\n|---|---|---\nMAIN | 主线程（UI线程） | /\nASYNC | 异步线程（开子线程，普通线程池） | 核心线程数和最大线程为CPU数，0s keepTime，LinkedBlockingQueue（128），线程优先级5\nASYNC_IO | 异步线程（开子线程，io线程池） | 核心线程数和最大线程为(2*CPU数+1)，30s keepTime，LinkedBlockingQueue（128），线程优先级5\nASYNC_EMERGENT | 异步线程（开子线程，紧急线程池） | 核心线程数为2，最大线程为∞，60s keepTime，SynchronousQueue（不阻塞），线程优先级10\nASYNC_BACKGROUND | 异步线程（开子线程，优先级较低线程池） | 核心线程数和最大线程为2，0s keepTime，LinkedBlockingQueue（128），线程优先级1\nSYNC | 同步线程（直接执行） | /\n\n```\n// 1.构造时传入线程\nXTaskStep taskStep = XTask.getTask(new SimpleTaskCommand(1000), ThreadType.ASYNC_EMERGENT);\n// 2.设置线程的方法\ntaskStep.setThreadType(ThreadType.ASYNC_IO);\n```\n\n## 任务组\n\n目前共有串行任务组（SerialGroupTaskStep）和并行任务组（ConcurrentGroupTaskStep）\n\n### 串行任务组\n\n串行任务组是按顺序依次执行，和任务链的处理方式类似。使用XTask.getSerialGroupTask获取。\n\n```\nfinal TaskChainEngine engine = XTask.getTaskChain();\nSerialGroupTaskStep group1 = XTask.getSerialGroupTask(\"group1\");\nfor (int i = 0; i \u003c 5; i++) {\n    group1.addTask(XTask.getTask(new SimpleTaskCommand(500)));\n}\nSerialGroupTaskStep group2 = XTask.getSerialGroupTask(\"group2\");\nfor (int i = 0; i \u003c 5; i++) {\n    group2.addTask(XTask.getTask(new SimpleTaskCommand(1000)));\n}\nICanceller canceller = engine.addTask(group1)\n        .addTask(group2)\n        .setTaskChainCallback(new TaskChainCallbackAdapter() {\n            @Override\n            public void onTaskChainCompleted(@NonNull ITaskChainEngine engine, @NonNull ITaskResult result) {\n                Log.e(TAG, \"task chain completed, path:\" + result.getPath());\n            }\n        })\n        .start();\naddCanceller(canceller);\n```\n\n### 并行任务组\n\n并行任务组是组内所有任务同时执行，待所有任务都完成后才视为任务组完成。使用XTask.getConcurrentGroupTask获取。\n\n```\nfinal TaskChainEngine engine = XTask.getTaskChain();\nConcurrentGroupTaskStep group1 = XTask.getConcurrentGroupTask(\"group1\");\nfor (int i = 0; i \u003c 5; i++) {\n    group1.addTask(XTask.getTask(new SimpleTaskCommand(100 * (i + 1))));\n}\nConcurrentGroupTaskStep group2 = XTask.getConcurrentGroupTask(\"group2\");\nfor (int i = 0; i \u003c 5; i++) {\n    group2.addTask(XTask.getTask(new SimpleTaskCommand(200 * (i + 1))));\n}\nICanceller canceller = engine.addTask(group1)\n        .addTask(group2)\n        .setTaskChainCallback(new TaskChainCallbackAdapter() {\n            @Override\n            public void onTaskChainCompleted(@NonNull ITaskChainEngine engine, @NonNull ITaskResult result) {\n                Log.e(TAG, \"task chain completed, path:\" + result.getPath());\n            }\n        })\n        .start();\naddCanceller(canceller);\n```\n\n## 任务链取消\n\n\u003e 通过调用`ICanceller`的`cancel`方法或者`XTask`的`cancelTaskChain`即可完成任务链的取消。\n\n### 单个任务链取消\n\n调用任务链`TaskChainEngine`的`start`方法之后，会返回一个任务取消者`ICanceller`，调用它的`cancel`方法即可完成任务取消。\n\n```\nICanceller canceller = engine.start();\n// 取消任务链的执行\ncanceller.cancel();\n```\n\n### 多个任务链取消\n\n任务链在执行的时候，会默认加入到一个任务取消池，调用`XTask`的`cancelTaskChain`方法，传入多个任务链的名称或者`ICanceller`的名称，即可完成多个任务链的取消。\n\n```\nSet\u003cString\u003e pool = new HashSet\u003c\u003e();\nICanceller canceller1 = engine1.start();\nICanceller canceller2 = engine2.start();\n// 使用ICanceller的名称\npool.add(canceller1.getName());\n// 使用任务链的名称\npool.add(engine2.getName());\n// 取消多个任务链的执行\nXTask.cancelTaskChain(pool);\n```\n\n### 全部任务链取消\n\n调用`XTask`的`cancelAllTaskChain`方法取消全部任务链的执行\n\n```\nXTask.cancelAllTaskChain();\n```\n\n---\n\n## 如果觉得项目还不错，可以考虑打赏一波\n\n\u003e 你的打赏是我维护的动力，我将会列出所有打赏人员的清单在下方作为凭证，打赏前请留下打赏项目的备注！\n\n![pay.png](https://raw.githubusercontent.com/xuexiangjys/Resource/master/img/pay/pay.png)\n\n## 联系方式\n\n\u003e 更多资讯内容，欢迎扫描关注我的个人微信公众号:【我的Android开源之旅】\n\n![](https://s1.ax1x.com/2022/04/27/LbGMJH.jpg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxuexiangjys%2Fxtask","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxuexiangjys%2Fxtask","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxuexiangjys%2Fxtask/lists"}