SwiftHttp: swif http 访问

原作者: [db:作者] 来自: 网络收藏邀请

开源软件名称：

SwiftHttp

开源软件地址：

https://gitee.com/knight2015/SwiftHttp

开源软件介绍：

Alamofire: Elegant Networking in Swift

Alamofire is an HTTP networking library written in Swift, from the creator of AFNetworking.

Features

Chainable Request / Response methods
URL / JSON / plist Parameter Encoding
Upload File / Data / Stream
Download using Request or Resume data
Authentication with NSURLCredential
HTTP Response Validation
Progress Closure & NSProgress
cURL Debug Output
Comprehensive Unit Test Coverage
Complete Documentation

Requirements

iOS 7.0+ / Mac OS X 10.9+
Xcode 6.0

For Xcode 6.1, use the xcode-6.1 branch.

Communication

If you need help, use Stack Overflow. (Tag 'alamofire')
If you'd like to ask a general question, use Stack Overflow.
If you found a bug, open an issue.
If you have a feature request, open an issue.
If you want to contribute, submit a pull request.

Installation

Due to the current lack of proper infrastructure for Swift dependency management, using Alamofire in your project requires the following steps:

Add Alamofire as a submodule by opening the Terminal, cd-ing into your top-level project directory, and entering the command git submodule add https://github.com/Alamofire/Alamofire.git
Open the Alamofire folder, and drag Alamofire.xcodeproj into the file navigator of your app project.
In Xcode, navigate to the target configuration window by clicking on the blue project icon, and selecting the application target under the "Targets" heading in the sidebar.
Ensure that the deployment target of Alamofire.framework matches that of the application target.
In the tab bar at the top of that window, open the "Build Phases" panel.
Expand the "Link Binary with Libraries" group, and add Alamofire.framework.
Click on the + button at the top left of the panel and select "New Copy Files Phase". Rename this new phase to "Copy Frameworks", set the "Destination" to "Frameworks", and add Alamofire.framework.

Usage

Making a Request

import AlamofireAlamofire.request(.GET, "http://httpbin.org/get")

Response Handling

Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])         .response { (request, response, data, error) in                     println(request)                     println(response)                     println(error)                   }

Networking in Alamofire is done asynchronously. Asynchronous programming may be a source of frustration to programmers unfamiliar with the concept, but there are very good reasons for doing it this way.

Rather than blocking execution to wait for a response from the server, a callback is specified to handle the response once it's received. The result of a request is only available inside the scope of a response handler. Any execution contingent on the response or data received from the server must be done within a handler.

Response Serialization

Built-in Response Methods

response()
responseString(encoding: NSStringEncoding)
responseJSON(options: NSJSONReadingOptions)
responsePropertyList(options: NSPropertyListReadOptions)

Response String Handler

Alamofire.request(.GET, "http://httpbin.org/get")         .responseString { (_, _, string, _) in                  println(string)         }

Response JSON Handler

Alamofire.request(.GET, "http://httpbin.org/get")         .responseJSON { (_, _, JSON, _) in                  println(JSON)         }

Chained Response Handlers

Response handlers can even be chained:

Alamofire.request(.GET, "http://httpbin.org/get")         .responseString { (_, _, string, _) in                  println(string)         }         .responseJSON { (_, _, JSON, _) in                  println(JSON)         }

HTTP Methods

Alamofire.Method lists the HTTP methods defined in RFC 7231 §4.3:

public enum Method: String {    case OPTIONS = "OPTIONS"    case GET = "GET"    case HEAD = "HEAD"    case POST = "POST"    case PUT = "PUT"    case PATCH = "PATCH"    case DELETE = "DELETE"    case TRACE = "TRACE"    case CONNECT = "CONNECT"}

These values can be passed as the first argument of the Alamofire.request method:

Alamofire.request(.POST, "http://httpbin.org/post")Alamofire.request(.PUT, "http://httpbin.org/put")Alamofire.request(.DELETE, "http://httpbin.org/delete")

Parameters

GET Request With URL-Encoded Parameters

Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])// http://httpbin.org/get?foo=bar

POST Request With URL-Encoded Parameters

let parameters = [    "foo": "bar",    "baz": ["a", 1],    "qux": [        "x": 1,        "y": 2,        "z": 3    ]]Alamofire.request(.POST, "http://httpbin.org/post", parameters: parameters)// HTTP body: foo=bar&baz[]=a&baz[]=1&qux[x]=1&qux[y]=2&qux[z]=3

Parameter Encoding

Parameters can also be encoded as JSON, Property List, or any custom format, using the ParameterEncoding enum:

enum ParameterEncoding {    case URL    case JSON    case PropertyList(format: NSPropertyListFormat,                      options: NSPropertyListWriteOptions)    func encode(request: NSURLRequest,                parameters: [String: AnyObject]?) ->                    (NSURLRequest, NSError?)    { ... }}

URL: A query string to be set as or appended to any existing URL query for GET, HEAD, and DELETE requests, or set as the body for requests with any other HTTP method. The Content-Type HTTP header field of an encoded request with HTTP body is set to application/x-www-form-urlencoded. Since there is no published specification for how to encode collection types, the convention of appending [] to the key for array values (foo[]=1&foo[]=2), and appending the key surrounded by square brackets for nested dictionary values (foo[bar]=baz).
JSON: Uses NSJSONSerialization to create a JSON representation of the parameters object, which is set as the body of the request. The Content-Type HTTP header field of an encoded request is set to application/json.
PropertyList: Uses NSPropertyListSerialization to create a plist representation of the parameters object, according to the associated format and write options values, which is set as the body of the request. The Content-Type HTTP header field of an encoded request is set to application/x-plist.
Custom: Uses the associated closure value to construct a new request given an existing request and parameters.

Manual Parameter Encoding of an NSURLRequest

let URL = NSURL(string: "http://httpbin.org/get")var request = NSURLRequest(URL: URL)let parameters = ["foo": "bar"]let encoding = Alamofire.ParameterEncoding.URL(request, _) = encoding.encode(request, parameters)

POST Request with JSON-encoded Parameters

let parameters = [    "foo": [1,2,3],    "bar": [        "baz": "qux"    ]]Alamofire.request(.POST, "http://httpbin.org/post", parameters: parameters, encoding: .JSON)// HTTP body: {"foo": [1, 2, 3], "bar": {"baz": "qux"}}

Caching

Caching is handled on the system framework level by NSURLCache.

Uploading

Supported Upload Types

File
Data
Stream

Uploading a File

let fileURL = NSBundle.mainBundle()                      .URLForResource("Default",                                      withExtension: "png")Alamofire.upload(.POST, "http://httpbin.org/post", file: fileURL)

Uploading w/Progress

Alamofire.upload(.POST, "http://httpbin.org/post", file: fileURL)         .progress { (bytesWritten, totalBytesWritten, totalBytesExpectedToWrite) in             println(totalBytesWritten)         }         .responseJSON { (request, response, JSON, error) in             println(JSON)         }

Downloading

Supported Download Types

Request
Resume Data

Downloading a File

Alamofire.download(.GET, "http://httpbin.org/stream/100", destination: { (temporaryURL, response) in    if let directoryURL = NSFileManager.defaultManager()                          .URLsForDirectory(.DocumentDirectory,                                            inDomains: .UserDomainMask)[0]                          as? NSURL {        let pathComponent = response.suggestedFilename        return directoryURL.URLByAppendingPathComponent(pathComponent!)    }    return temporaryURL})

Using the Default Download Destination

let destination = Alamofire.Request.suggestedDownloadDestination(directory: .DocumentDirectory, domain: .UserDomainMask)Alamofire.download(.GET, "http://httpbin.org/stream/100", destination: destination)

Downloading a File w/Progress

Alamofire.download(.GET, "http://httpbin.org/stream/100", destination: destination)         .progress { (bytesRead, totalBytesRead, totalBytesExpectedToRead) in             println(totalBytesRead)         }         .response { (request, response, _, error) in             println(response)         }

Authentication

Authentication is handled on the system framework level by NSURLCredential and NSURLAuthenticationChallenge.

Supported Authentication Schemes

HTTP Basic
HTTP Digest
Kerberos
NTLM

HTTP Basic Authentication

let user = "user"let password = "password"Alamofire.request(.GET, "https://httpbin.org/basic-auth/\(user)/\(password)")         .authenticate(user: user, password: password)         .response {(request, response, _, error) in             println(response)         }

Authentication with NSURLCredential

let user = "user"let password = "password"let credential = NSURLCredential(user: user, password: password, persistence: .ForSession)Alamofire.request(.GET, "https://httpbin.org/basic-auth/\(user)/\(password)")         .authenticate(usingCredential: credential)         .response {(request, response, _, error) in             println(response)         }

Validation

By default, Alamofire treats any completed request to be successful, regardless of the content of the response. Calling validate before a response handler causes an error to be generated if the response had an unacceptable status code or MIME type.

Manual Validation

Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])         .validate(statusCode: 200..<300)         .validate(contentType: ["application/json"])         .response { (_, _, _, error) in                  println(error)         }

Automatic Validation

Automatically validates status code within 200...299 range, and that the Content-Type header of the response matches the Accept header of the request, if one is provided.

Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])         .validate()         .response { (_, _, _, error) in                  println(error)         }

Printable

let request = Alamofire.request(.GET, "http://httpbin.org/ip")println(request)// GET http://httpbin.org/ip (200)

DebugPrintable

let request = Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])debugPrintln(request)

Output (cURL)

$ curl -i \	-H "User-Agent: Alamofire" \	-H "Accept-Encoding: Accept-Encoding: gzip;q=1.0,compress;q=0.5" \	-H "Accept-Language: en;q=1.0,fr;q=0.9,de;q=0.8,zh-Hans;q=0.7,zh-Hant;q=0.6,ja;q=0.5" \	"http://httpbin.org/get?foo=bar"

Advanced Usage

Alamofire is built on NSURLSession and the Foundation URL Loading System. To make the most ofthis framework, it is recommended that you be familiar with the concepts and capabilities of the underlying networking stack.

Recommended Reading

URL Loading System Programming Guide
NSURLSession Class Reference
NSURLCache Class Reference
NSURLAuthenticationChallenge Class Reference

Manager

Top-level convenience methods like Alamofire.request use a shared instance of Alamofire.Manager, which is configured with the default NSURLSessionConfiguration.

As such, the following two statements are equivalent:

Alamofire.request(.GET, "http://httpbin.org/get")

let manager = Alamofire.Manager.sharedInstancemanager.request(NSURLRequest(URL: NSURL(string: "http://httpbin.org/get")))

Applications can create managers for background and ephemeral sessions, as well as new managers that customize the default session configuration, such as for default headers (HTTPAdditionalHeaders) or timeout interval (timeoutIntervalForRequest).

Creating a Manager with Default Configuration

let configuration = NSURLSessionConfiguration.defaultSessionConfiguration()let manager = Alamofire.Manager(configuration: configuration)

Creating a Manager with Background Configuration

let configuration = NSURLSessionConfiguration.backgroundSessionConfiguration("com.example.app.background")let manager = Alamofire.Manager(configuration: configuration)

Creating a Manager with Ephemeral Configuration

let configuration = NSURLSessionConfiguration.ephemeralSessionConfiguration()let manager = Alamofire.Manager(configuration: configuration)

Modifying Session Configuration

var defaultHeaders = Alamofire.Manager.sharedInstance.session.configuration.HTTPAdditionalHeaders ?? [:]defaultHeaders["DNT"] = "1 (Do Not Track Enabled)"let configuration = NSURLSessionConfiguration.defaultSessionConfiguration()configuration.HTTPAdditionalHeaders = defaultHeaderslet manager = Alamofire.Manager(configuration: configuration)

This is not recommended for Authorization or Content-Type headers. Instead, use URLRequestConvertible and ParameterEncoding, respectively.

Request

The result of a request, upload, or download method is an instance of Alamofire.Request. A request is always created using a constructor method from an owning manager, and never initialized directly.

Methods like authenticate, validate, and response return the caller in order to facilitate chaining.

Requests can be suspended, resumed, and cancelled:

suspend(): Suspends the underlying task and dispatch queue
resume(): Resumes the underlying task and dispatch queue. If the owning manager does not have startRequestsImmediately set to true, the request must call resume() in order to start.
cancel(): Cancels the underlying task, producing an error that is passed to any registered response handlers.

Response Serialization

Creating a Custom Response Serializer

Alamofire provides built-in response serialization for strings, JSON, and property lists, but others can be added in extensions on Alamofire.Request.

For example, here's how a response handler using Ono might be implemented:

extension Request {    class func XMLResponseSerializer() -> Serializer {        return { (request, response, data) in            if data == nil {                return (nil, nil)            }            var XMLSerializationError: NSError?            let XML = ONOXMLDocument.XMLDocumentWithData(data, &XMLSerializationError)            return (XML, XMLSerializationError)        }    }    func responseXMLDocument(completionHandler: (NSURLRequest, NSHTTPURLResponse?, OnoXMLDocument?, NSError?) -> Void) -> Self {        return response(serializer: Request.XMLResponseSerializer(), completionHandler: { (request, response, XML, error) in            completionHandler(request, response, XML, error)        })    }}

Generic Response Object Serialization

Generics can be used to provide automatic, type-safe response object serialization.

@objc public protocol ResponseObjectSerializable {    init(response: NSHTTPURLResponse, representation: AnyObject)}extension Alamofire.Request {    public func responseObject<T: ResponseObjectSerializable>(completionHandler: (NSURLRequest, NSHTTPURLResponse?, T?, NSError?) -> Void) -> Self {        let serializer: Serializer = { (request, response, data) in            let JSONSerializer = Request.JSONResponseSerializer(options: .AllowFragments)            let (JSON: AnyObject?, serializationError) = JSONSerializer(request, response, data)            if response != nil && JSON != nil {                return (T(response: response!, representation: JSON!), nil)            } else {                return (nil, serializationError)            }        }<